Welcome to PyWayland’s 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 pywaland/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¶

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 flake8, 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: Union[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 ueue 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: Optional[pywayland.client.eventqueue.EventQueue] = None) → int¶

Process incoming events

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

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

Note

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

flush() → int¶

Send all buffered requests on the display to the server

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

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

get_fd() → int¶

Get a display context’s file descriptor

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

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

Read events from display file descriptor

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

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

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

Block until all pending request are processed by the server

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

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

Note

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

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

EventQueue¶

class pywayland.client.EventQueue(display: 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.

Server Modules¶

The base set of objects used by Wayland servers.

Client¶

class pywayland.server.Client(display: pywayland.server.display.Display, fd: int)¶

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.

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

add_destroy_listener(listener: pywayland.server.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.

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: Optional[str] = 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.

EventLoop¶

class pywayland.server.EventLoop(display: Optional[Display] = 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¶: An enumeration.

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

Listener¶

class pywayland.server.Listener(function)¶

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()¶: 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, version: Optional[int] = 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, version: Optional[int] = 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()¶: Frees the pointer associated with the Proxy

destroyed¶

Determine if proxy has been destroyed

Returns true if the proxy has been destroyed.

Resource¶

class pywayland.protocol_core.Resource(client, version=None, id=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)¶

Add a listener for the destroy signal

Parameters:	listener (`Listener`) – The listener object

destroy()¶: 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[pywayland.protocol_core.argument.Argument], version: Optional[int])¶

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: pywayland.scanner.argument.ArgumentType, nullable: bool = False, interface: Union[Type[ForwardRef('Interface')], NoneType] = None)¶

ArgumentType¶

class pywayland.protocol_core.argument.ArgumentType¶: An enumeration.

Protocol Modules¶

Wayland protocols built against Wayland 1.18.0 and Wayland Protocols 1.20.

fullscreen_shell_unstable_v1 Module¶

ZwpFullscreenShellV1¶

class pywayland.protocol.fullscreen_shell_unstable_v1.ZwpFullscreenShellV1¶

Displays a single surface per output

Displays a single surface per output.

This interface provides a mechanism for a single client to display simple full-screen surfaces. While there technically may be multiple clients bound to this interface, only one of those clients should be shown at a time.

To present a surface, the client uses either the present_surface or present_surface_for_mode requests. Presenting a surface takes effect on the next WlSurface.commit(). See the individual requests for details about scaling and mode switches.

The client can have at most one surface per output at any time. Requesting a surface to be presented on an output that already has a surface replaces the previously presented surface. Presenting a null surface removes its content and effectively disables the output. Exactly what happens when an output is “disabled” is compositor-specific. The same surface may be presented on multiple outputs simultaneously.

Once a surface is presented on an output, it stays on that output until either the client removes it or the compositor destroys the output. This way, the client can update the output’s contents by simply attaching a new buffer.

Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.

release()¶

Request – opcode 0 (attached to Resource instance)

Release the wl_fullscreen_shell interface

Release the binding from the wl_fullscreen_shell interface.

This destroys the server-side object and frees this binding. If the client binds to wl_fullscreen_shell multiple times, it may wish to free some of those bindings.

present_surface(surface, method, output)¶

Request – opcode 1 (attached to Resource instance)

Present surface for display

Present a surface on the given output.

If the output is null, the compositor will present the surface on whatever display (or displays) it thinks best. In particular, this may replace any or all surfaces currently presented so it should not be used in combination with placing surfaces on specific outputs.

The method parameter is a hint to the compositor for how the surface is to be presented. In particular, it tells the compositor how to handle a size mismatch between the presented surface and the output. The compositor is free to ignore this parameter.

The “zoom”, “zoom_crop”, and “stretch” methods imply a scaling operation on the surface. This will override any kind of output scaling, so the buffer_scale property of the surface is effectively ignored.

Parameters:	surface (`WlSurface` or None) – method (ArgumentType.Uint) – output (`WlOutput` or None) –

present_surface_for_mode(surface, output, framerate)¶

Request – opcode 2 (attached to Resource instance)

Present surface for display at a particular mode

Presents a surface on the given output for a particular mode.

If the current size of the output differs from that of the surface, the compositor will attempt to change the size of the output to match the surface. The result of the mode-switch operation will be returned via the provided wl_fullscreen_shell_mode_feedback object.

If the current output mode matches the one requested or if the compositor successfully switches the mode to match the surface, then the mode_successful event will be sent and the output will contain the contents of the given surface. If the compositor cannot match the output size to the surface size, the mode_failed will be sent and the output will contain the contents of the previously presented surface (if any). If another surface is presented on the given output before either of these has a chance to happen, the present_cancelled event will be sent.

Due to race conditions and other issues unknown to the client, no mode- switch operation is guaranteed to succeed. However, if the mode is one advertised by WlOutput.mode() or if the compositor advertises the ARBITRARY_MODES capability, then the client should expect that the mode-switch operation will usually succeed.

If the size of the presented surface changes, the resulting output is undefined. The compositor may attempt to change the output mode to compensate. However, there is no guarantee that a suitable mode will be found and the client has no way to be notified of success or failure.

The framerate parameter specifies the desired framerate for the output in mHz. The compositor is free to ignore this parameter. A value of 0 indicates that the client has no preference.

If the value of WlOutput.scale() differs from WlSurface.buffer_scale(), then the compositor may choose a mode that matches either the buffer size or the surface size. In either case, the surface will fill the output.

Parameters:	surface (`WlSurface`) – output (`WlOutput`) – framerate (ArgumentType.Int) –
Returns:	`ZwpFullscreenShellModeFeedbackV1`

capability(capability)¶

Event – opcode 0 (attached to Proxy instance)

Advertises a capability of the compositor

Advertises a single capability of the compositor.

When the wl_fullscreen_shell interface is bound, this event is emitted once for each capability advertised. Valid capabilities are given by the wl_fullscreen_shell.capability enum. If clients want to take advantage of any of these capabilities, they should use a WlDisplay.sync() request immediately after binding to ensure that they receive all the capability events.

Parameters:	capability (ArgumentType.Uint) –

ZwpFullscreenShellModeFeedbackV1¶

class pywayland.protocol.fullscreen_shell_unstable_v1.ZwpFullscreenShellModeFeedbackV1¶

mode_successful()¶

Event – opcode 0 (attached to Proxy instance)

Mode switch succeeded

This event indicates that the attempted mode switch operation was successful. A surface of the size requested in the mode switch will fill the output without scaling.

Upon receiving this event, the client should destroy the wl_fullscreen_shell_mode_feedback object.

mode_failed()¶

Event – opcode 1 (attached to Proxy instance)

Mode switch failed

This event indicates that the attempted mode switch operation failed. This may be because the requested output mode is not possible or it may mean that the compositor does not want to allow it.

Upon receiving this event, the client should destroy the wl_fullscreen_shell_mode_feedback object.

present_cancelled()¶

Event – opcode 2 (attached to Proxy instance)

Mode switch cancelled

This event indicates that the attempted mode switch operation was cancelled. Most likely this is because the client requested a second mode switch before the first one completed.

Upon receiving this event, the client should destroy the wl_fullscreen_shell_mode_feedback object.

idle_inhibit_unstable_v1 Module¶

ZwpIdleInhibitorV1¶

class pywayland.protocol.idle_inhibit_unstable_v1.ZwpIdleInhibitorV1¶

Context object for inhibiting idle behavior

An idle inhibitor prevents the output that the associated surface is visible on from being set to a state where it is not visually usable due to lack of user interaction (e.g. blanked, dimmed, locked, set to power save, etc.) Any screensaver processes are also blocked from displaying.

If the surface is destroyed, unmapped, becomes occluded, loses visibility, or otherwise becomes not visually relevant for the user, the idle inhibitor will not be honored by the compositor; if the surface subsequently regains visibility the inhibitor takes effect once again. Likewise, the inhibitor isn’t honored if the system was already idled at the time the inhibitor was established, although if the system later de-idles and re-idles the inhibitor will take effect.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the idle inhibitor object

Remove the inhibitor effect from the associated WlSurface.

ZwpIdleInhibitManagerV1¶

class pywayland.protocol.idle_inhibit_unstable_v1.ZwpIdleInhibitManagerV1¶

Control behavior when display idles

This interface permits inhibiting the idle behavior such as screen blanking, locking, and screensaving. The client binds the idle manager globally, then creates idle-inhibitor objects for each surface.

Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the idle inhibitor object

Destroy the inhibit manager.

create_inhibitor(surface)¶

Request – opcode 1 (attached to Resource instance)

Create a new inhibitor object

Create a new inhibitor object associated with the given surface.

Parameters:	surface (`WlSurface`) – the surface that inhibits the idle behavior
Returns:	`ZwpIdleInhibitorV1`

input_method_unstable_v1 Module¶

ZwpInputPanelV1¶

class pywayland.protocol.input_method_unstable_v1.ZwpInputPanelV1¶

Interface for implementing keyboards

Only one client can bind this interface at a time.

get_input_panel_surface(surface)¶

Request – opcode 0 (attached to Resource instance)

get_input_panel_surface

Parameters:	surface (`WlSurface`) –
Returns:	`ZwpInputPanelSurfaceV1`

ZwpInputMethodV1¶

class pywayland.protocol.input_method_unstable_v1.ZwpInputMethodV1¶

Input method

An input method object is responsible for composing text in response to input from hardware or virtual keyboards. There is one input method object per seat. On activate there is a new input method context object created which allows the input method to communicate with the text input.

activate(id)¶

Event – opcode 0 (attached to Proxy instance)

Activate event

A text input was activated. Creates an input method context object which allows communication with the text input.

Parameters:	id (`ZwpInputMethodContextV1`) –

deactivate(context)¶

Event – opcode 1 (attached to Proxy instance)

Deactivate event

The text input corresponding to the context argument was deactivated. The input method context should be destroyed after deactivation is handled.

Parameters:	context (`ZwpInputMethodContextV1`) –

ZwpInputMethodContextV1¶

class pywayland.protocol.input_method_unstable_v1.ZwpInputMethodContextV1¶

Input method context

Corresponds to a text input on the input method side. An input method context is created on text input activation on the input method side. It allows receiving information about the text input from the application via events. Input method contexts do not keep state after deactivation and should be destroyed after deactivation is handled.

Text is generally UTF-8 encoded, indices and lengths are in bytes.

Serials are used to synchronize the state between the text input and an input method. New serials are sent by the text input in the commit_state request and are used by the input method to indicate the known text input state in events like preedit_string, commit_string, and keysym. The text input can then ignore events from the input method which are based on an outdated state (for example after a reset).

Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.

destroy()¶

Request – opcode 0 (attached to Resource instance)

destroy

commit_string(serial, text)¶

Request – opcode 1 (attached to Resource instance)

Commit string

Send the commit string text for insertion to the application.

The text to commit could be either just a single character after a key press or the result of some composing (pre-edit). It could be also an empty text when some text should be removed (see delete_surrounding_text) or when the input cursor should be moved (see cursor_position).

Any previously set composing text will be removed.

Parameters:	serial (ArgumentType.Uint) – serial of the latest known text input state text (ArgumentType.String) –

preedit_string(serial, text, commit)¶

Request – opcode 2 (attached to Resource instance)

Pre-edit string

Send the pre-edit string text to the application text input.

The commit text can be used to replace the pre-edit text on reset (for example on unfocus).

Previously sent preedit_style and preedit_cursor requests are also processed by the text_input.

Parameters:	serial (ArgumentType.Uint) – serial of the latest known text input state text (ArgumentType.String) – commit (ArgumentType.String) –

preedit_styling(index, length, style)¶

Request – opcode 3 (attached to Resource instance)

Pre-edit styling

Set the styling information on composing text. The style is applied for length in bytes from index relative to the beginning of the composing text (as byte offset). Multiple styles can be applied to a composing text.

This request should be sent before sending a preedit_string request.

Parameters:	index (ArgumentType.Uint) – length (ArgumentType.Uint) – style (ArgumentType.Uint) –

preedit_cursor(index)¶

Request – opcode 4 (attached to Resource instance)

Pre-edit cursor

Set the cursor position inside the composing text (as byte offset) relative to the start of the composing text.

When index is negative no cursor should be displayed.

This request should be sent before sending a preedit_string request.

Parameters:	index (ArgumentType.Int) –

delete_surrounding_text(index, length)¶

Request – opcode 5 (attached to Resource instance)

Delete text

Remove the surrounding text.

This request will be handled on the text_input side directly following a commit_string request.

Parameters:	index (ArgumentType.Int) – length (ArgumentType.Uint) –

cursor_position(index, anchor)¶

Request – opcode 6 (attached to Resource instance)

Set cursor to a new position

Set the cursor and anchor to a new position. Index is the new cursor position in bytes (when >= 0 this is relative to the end of the inserted text, otherwise it is relative to the beginning of the inserted text). Anchor is the new anchor position in bytes (when >= 0 this is relative to the end of the inserted text, otherwise it is relative to the beginning of the inserted text). When there should be no selected text, anchor should be the same as index.

This request will be handled on the text_input side directly following a commit_string request.

Parameters:	index (ArgumentType.Int) – anchor (ArgumentType.Int) –

modifiers_map(map)¶

Request – opcode 7 (attached to Resource instance)

modifiers_map

Parameters:	map (ArgumentType.Array) –

keysym(serial, time, sym, state, modifiers)¶

Request – opcode 8 (attached to Resource instance)

Keysym

Notify when a key event was sent. Key events should not be used for normal text input operations, which should be done with commit_string, delete_surrounding_text, etc. The key event follows the WlKeyboard key event convention. Sym is an XKB keysym, state is a WlKeyboard key_state.

Parameters:	serial (ArgumentType.Uint) – serial of the latest known text input state time (ArgumentType.Uint) – sym (ArgumentType.Uint) – state (ArgumentType.Uint) – modifiers (ArgumentType.Uint) –

grab_keyboard()¶

Request – opcode 9 (attached to Resource instance)

Grab hardware keyboard

Allow an input method to receive hardware keyboard input and process key events to generate text events (with pre-edit) over the wire. This allows input methods which compose multiple key events for inputting text like it is done for CJK languages.

Returns:	`WlKeyboard`

key(serial, time, key, state)¶

Request – opcode 10 (attached to Resource instance)

Forward key event

Forward a WlKeyboard::key event to the client that was not processed by the input method itself. Should be used when filtering key events with grab_keyboard. The arguments should be the ones from the WlKeyboard::key event.

For generating custom key events use the keysym request instead.

Parameters:	serial (ArgumentType.Uint) – serial from `WlKeyboard`::key time (ArgumentType.Uint) – time from `WlKeyboard`::key key (ArgumentType.Uint) – key from `WlKeyboard`::key state (ArgumentType.Uint) – state from `WlKeyboard`::key

modifiers(serial, mods_depressed, mods_latched, mods_locked, group)¶

Request – opcode 11 (attached to Resource instance)

Forward modifiers event

Forward a WlKeyboard::modifiers event to the client that was not processed by the input method itself. Should be used when filtering key events with grab_keyboard. The arguments should be the ones from the WlKeyboard::modifiers event.

Parameters:	serial (ArgumentType.Uint) – serial from `WlKeyboard`::modifiers mods_depressed (ArgumentType.Uint) – mods_depressed from `WlKeyboard`::modifiers mods_latched (ArgumentType.Uint) – mods_latched from `WlKeyboard`::modifiers mods_locked (ArgumentType.Uint) – mods_locked from `WlKeyboard`::modifiers group (ArgumentType.Uint) – group from `WlKeyboard`::modifiers

language(serial, language)¶

Request – opcode 12 (attached to Resource instance)

language

Parameters:	serial (ArgumentType.Uint) – serial of the latest known text input state language (ArgumentType.String) –

text_direction(serial, direction)¶

Request – opcode 13 (attached to Resource instance)

text_direction

Parameters:	serial (ArgumentType.Uint) – serial of the latest known text input state direction (ArgumentType.Uint) –

surrounding_text(text, cursor, anchor)¶

Event – opcode 0 (attached to Proxy instance)

Surrounding text event

The plain surrounding text around the input position. Cursor is the position in bytes within the surrounding text relative to the beginning of the text. Anchor is the position in bytes of the selection anchor within the surrounding text relative to the beginning of the text. If there is no selected text then anchor is the same as cursor.

Parameters:	text (ArgumentType.String) – cursor (ArgumentType.Uint) – anchor (ArgumentType.Uint) –

reset()¶

Event – opcode 1 (attached to Proxy instance)

reset

content_type(hint, purpose)¶

Event – opcode 2 (attached to Proxy instance)

content_type

Parameters:	hint (ArgumentType.Uint) – purpose (ArgumentType.Uint) –

invoke_action(button, index)¶

Event – opcode 3 (attached to Proxy instance)

invoke_action

Parameters:	button (ArgumentType.Uint) – index (ArgumentType.Uint) –

commit_state(serial)¶

Event – opcode 4 (attached to Proxy instance)

commit_state

Parameters:	serial (ArgumentType.Uint) – serial of text input state

preferred_language(language)¶

Event – opcode 5 (attached to Proxy instance)

preferred_language

Parameters:	language (ArgumentType.String) –

ZwpInputPanelSurfaceV1¶

class pywayland.protocol.input_method_unstable_v1.ZwpInputPanelSurfaceV1¶

set_toplevel(output, position)¶

Request – opcode 0 (attached to Resource instance)

Set the surface type as a keyboard

Set the input_panel_surface type to keyboard.

A keyboard surface is only shown when a text input is active.

Parameters:	output (`WlOutput`) – position (ArgumentType.Uint) –

set_overlay_panel()¶

Request – opcode 1 (attached to Resource instance)

Set the surface type as an overlay panel

Set the input_panel_surface to be an overlay panel.

This is shown near the input cursor above the application window when a text input is active.

input_timestamps_unstable_v1 Module¶

ZwpInputTimestampsV1¶

class pywayland.protocol.input_timestamps_unstable_v1.ZwpInputTimestampsV1¶

Context object for input timestamps

Provides high-resolution timestamp events for a set of subscribed input events. The set of subscribed input events is determined by the ZwpInputTimestampsManagerV1 request used to create this object.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the input timestamps object

Informs the server that the client will no longer be using this protocol object. After the server processes the request, no more timestamp events will be emitted.

timestamp(tv_sec_hi, tv_sec_lo, tv_nsec)¶

Event – opcode 0 (attached to Proxy instance)

High-resolution timestamp event

The timestamp event is associated with the first subsequent input event carrying a timestamp which belongs to the set of input events this object is subscribed to.

The timestamp provided by this event is a high-resolution version of the timestamp argument of the associated input event. The provided timestamp is in the same clock domain and is at least as accurate as the associated input event timestamp.

The timestamp is expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples, each component being an unsigned 32-bit value. Whole seconds are in tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo, and the additional fractional part in tv_nsec as nanoseconds. Hence, for valid timestamps tv_nsec must be in [0, 999999999].

Parameters:	tv_sec_hi (ArgumentType.Uint) – high 32 bits of the seconds part of the timestamp tv_sec_lo (ArgumentType.Uint) – low 32 bits of the seconds part of the timestamp tv_nsec (ArgumentType.Uint) – nanoseconds part of the timestamp

ZwpInputTimestampsManagerV1¶

class pywayland.protocol.input_timestamps_unstable_v1.ZwpInputTimestampsManagerV1¶

Context object for high-resolution input timestamps

A global interface used for requesting high-resolution timestamps for input events.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the input timestamps manager object

Informs the server that the client will no longer be using this protocol object. Existing objects created by this object are not affected.

get_keyboard_timestamps(keyboard)¶

Request – opcode 1 (attached to Resource instance)

Subscribe to high-resolution keyboard timestamp events

Creates a new input timestamps object that represents a subscription to high-resolution timestamp events for all WlKeyboard events that carry a timestamp.

If the associated WlKeyboard object is invalidated, either through client action (e.g. release) or server-side changes, the input timestamps object becomes inert and the client should destroy it by calling ZwpInputTimestampsV1.destroy().

Parameters:	keyboard (`WlKeyboard`) – the `WlKeyboard` object for which to get timestamp events
Returns:	`ZwpInputTimestampsV1`

get_pointer_timestamps(pointer)¶

Request – opcode 2 (attached to Resource instance)

Subscribe to high-resolution pointer timestamp events

Creates a new input timestamps object that represents a subscription to high-resolution timestamp events for all WlPointer events that carry a timestamp.

If the associated WlPointer object is invalidated, either through client action (e.g. release) or server- side changes, the input timestamps object becomes inert and the client should destroy it by calling ZwpInputTimestampsV1.destroy().

Parameters:	pointer (`WlPointer`) – the `WlPointer` object for which to get timestamp events
Returns:	`ZwpInputTimestampsV1`

get_touch_timestamps(touch)¶

Request – opcode 3 (attached to Resource instance)

Subscribe to high-resolution touch timestamp events

Creates a new input timestamps object that represents a subscription to high-resolution timestamp events for all WlTouch events that carry a timestamp.

If the associated WlTouch object becomes invalid, either through client action (e.g. release) or server- side changes, the input timestamps object becomes inert and the client should destroy it by calling ZwpInputTimestampsV1.destroy().

Parameters:	touch (`WlTouch`) – the `WlTouch` object for which to get timestamp events
Returns:	`ZwpInputTimestampsV1`

keyboard_shortcuts_inhibit_unstable_v1 Module¶

ZwpKeyboardShortcutsInhibitorV1¶

class pywayland.protocol.keyboard_shortcuts_inhibit_unstable_v1.ZwpKeyboardShortcutsInhibitorV1¶

Context object for keyboard shortcuts inhibitor

A keyboard shortcuts inhibitor instructs the compositor to ignore its own keyboard shortcuts when the associated surface has keyboard focus. As a result, when the surface has keyboard focus on the given seat, it will receive all key events originating from the specified seat, even those which would normally be caught by the compositor for its own shortcuts.

The Wayland compositor is however under no obligation to disable all of its shortcuts, and may keep some special key combo for its own use, including but not limited to one allowing the user to forcibly restore normal keyboard events routing in the case of an unwilling client. The compositor may also use the same key combo to reactivate an existing shortcut inhibitor that was previously deactivated on user request.

When the compositor restores its own keyboard shortcuts, an “inactive” event is emitted to notify the client that the keyboard shortcuts inhibitor is not effectively active for the surface and seat any more, and the client should not expect to receive all keyboard events.

When the keyboard shortcuts inhibitor is inactive, the client has no way to forcibly reactivate the keyboard shortcuts inhibitor.

The user can chose to re-enable a previously deactivated keyboard shortcuts inhibitor using any mechanism the compositor may offer, in which case the compositor will send an “active” event to notify the client.

If the surface is destroyed, unmapped, or loses the seat’s keyboard focus, the keyboard shortcuts inhibitor becomes irrelevant and the compositor will restore its own keyboard shortcuts but no “inactive” event is emitted in this case.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the keyboard shortcuts inhibitor object

Remove the keyboard shortcuts inhibitor from the associated WlSurface.

active()¶

Event – opcode 0 (attached to Proxy instance)

Shortcuts are inhibited

This event indicates that the shortcut inhibitor is active.

The compositor sends this event every time compositor shortcuts are inhibited on behalf of the surface. When active, the client may receive input events normally reserved by the compositor (see ZwpKeyboardShortcutsInhibitorV1).

This occurs typically when the initial request “inhibit_shortcuts” first becomes active or when the user instructs the compositor to re- enable and existing shortcuts inhibitor using any mechanism offered by the compositor.

inactive()¶

Event – opcode 1 (attached to Proxy instance)

Shortcuts are restored

This event indicates that the shortcuts inhibitor is inactive, normal shortcuts processing is restored by the compositor.

ZwpKeyboardShortcutsInhibitManagerV1¶

class pywayland.protocol.keyboard_shortcuts_inhibit_unstable_v1.ZwpKeyboardShortcutsInhibitManagerV1¶

Context object for keyboard grab_manager

A global interface used for inhibiting the compositor keyboard shortcuts.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the keyboard shortcuts inhibitor object

Destroy the keyboard shortcuts inhibitor manager.

inhibit_shortcuts(surface, seat)¶

Request – opcode 1 (attached to Resource instance)

Create a new keyboard shortcuts inhibitor object

Create a new keyboard shortcuts inhibitor object associated with the given surface for the given seat.

If shortcuts are already inhibited for the specified seat and surface, a protocol error “already_inhibited” is raised by the compositor.

Parameters:	surface (`WlSurface`) – the surface that inhibits the keyboard shortcuts behavior seat (`WlSeat`) – the `WlSeat` for which keyboard shortcuts should be disabled
Returns:	`ZwpKeyboardShortcutsInhibitorV1`

linux_dmabuf_unstable_v1 Module¶

ZwpLinuxBufferParamsV1¶

class pywayland.protocol.linux_dmabuf_unstable_v1.ZwpLinuxBufferParamsV1¶

Parameters for creating a dmabuf-based WlBuffer

This temporary object is a collection of dmabufs and other parameters that together form a single logical buffer. The temporary object may eventually create one WlBuffer unless cancelled by destroying it before requesting ‘create’.

Single-planar formats only require one dmabuf, however multi-planar formats may require more than one dmabuf. For all formats, an ‘add’ request must be called once per plane (even if the underlying dmabuf fd is identical).

You must use consecutive plane indices (‘plane_idx’ argument for ‘add’) from zero to the number of planes used by the drm_fourcc format code. All planes required by the format must be given exactly once, but can be given in any order. Each plane index can be set only once.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Delete this object, used or not

Cleans up the temporary data sent to the server for dmabuf-based WlBuffer creation.

add(fd, plane_idx, offset, stride, modifier_hi, modifier_lo)¶

Request – opcode 1 (attached to Resource instance)

Add a dmabuf to the temporary set

This request adds one dmabuf to the set in this ZwpLinuxBufferParamsV1.

The 64-bit unsigned value combined from modifier_hi and modifier_lo is the dmabuf layout modifier. DRM AddFB2 ioctl calls this the fb modifier, which is defined in drm_mode.h of Linux UAPI. This is an opaque token. Drivers use this token to express tiling, compression, etc. driver-specific modifications to the base format defined by the DRM fourcc code.

Warning: It should be an error if the format/modifier pair was not advertised with the modifier event. This is not enforced yet because some implementations always accept DRM_FORMAT_MOD_INVALID. Also version 2 of this protocol does not have the modifier event.

This request raises the PLANE_IDX error if plane_idx is too large. The error PLANE_SET is raised if attempting to set a plane that was already set.

Parameters:	fd (ArgumentType.FileDescriptor) – dmabuf fd plane_idx (ArgumentType.Uint) – plane index offset (ArgumentType.Uint) – offset in bytes stride (ArgumentType.Uint) – stride in bytes modifier_hi (ArgumentType.Uint) – high 32 bits of layout modifier modifier_lo (ArgumentType.Uint) – low 32 bits of layout modifier

create(width, height, format, flags)¶

Request – opcode 2 (attached to Resource instance)

Create a WlBuffer from the given dmabufs

This asks for creation of a WlBuffer from the added dmabuf buffers. The WlBuffer is not created immediately but returned via the ‘created’ event if the dmabuf sharing succeeds. The sharing may fail at runtime for reasons a client cannot predict, in which case the ‘failed’ event is triggered.

The ‘format’ argument is a DRM_FORMAT code, as defined by the libdrm’s drm_fourcc.h. The Linux kernel’s DRM sub-system is the authoritative source on how the format codes should work.

The ‘flags’ is a bitfield of the flags defined in enum “flags”. ‘y_invert’ means the that the image needs to be y-flipped.

Flag ‘interlaced’ means that the frame in the buffer is not progressive as usual, but interlaced. An interlaced buffer as supported here must always contain both top and bottom fields. The top field always begins on the first pixel row. The temporal ordering between the two fields is top field first, unless ‘bottom_first’ is specified. It is undefined whether ‘bottom_first’ is ignored if ‘interlaced’ is not set.

This protocol does not convey any information about field rate, duration, or timing, other than the relative ordering between the two fields in one buffer. A compositor may have to estimate the intended field rate from the incoming buffer rate. It is undefined whether the time of receiving WlSurface.commit() with a new buffer attached, applying the WlSurface state, WlSurface.frame() callback trigger, presentation, or any other point in the compositor cycle is used to measure the frame or field times. There is no support for detecting missed or late frames/fields/buffers either, and there is no support whatsoever for cooperating with interlaced compositor output.

The composited image quality resulting from the use of interlaced buffers is explicitly undefined. A compositor may use elaborate hardware features or software to deinterlace and create progressive output frames from a sequence of interlaced input buffers, or it may produce substandard image quality. However, compositors that cannot guarantee reasonable image quality in all cases are recommended to just reject all interlaced buffers.

Any argument errors, including non-positive width or height, mismatch between the number of planes and the format, bad format, bad offset or stride, may be indicated by fatal protocol errors: INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS.

Dmabuf import errors in the server that are not obvious client bugs are returned via the ‘failed’ event as non-fatal. This allows attempting dmabuf sharing and falling back in the client if it fails.

This request can be sent only once in the object’s lifetime, after which the only legal request is destroy. This object should be destroyed after issuing a ‘create’ request. Attempting to use this object after issuing ‘create’ raises ALREADY_USED protocol error.

It is not mandatory to issue ‘create’. If a client wants to cancel the buffer creation, it can just destroy this object.

Parameters:	width (ArgumentType.Int) – base plane width in pixels height (ArgumentType.Int) – base plane height in pixels format (ArgumentType.Uint) – DRM_FORMAT code flags (ArgumentType.Uint) – see enum flags

create_immed(width, height, format, flags)¶

Request – opcode 3 (attached to Resource instance)

Immediately create a WlBuffer from the given dmabufs

This asks for immediate creation of a WlBuffer by importing the added dmabufs.

In case of import success, no event is sent from the server, and the WlBuffer is ready to be used by the client.

Upon import failure, either of the following may happen, as seen fit by the implementation: - the client is terminated with one of the following fatal protocol errors: - INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS, in case of argument errors such as mismatch between the number of planes and the format, bad format, non-positive width or height, or bad offset or stride. - INVALID_WL_BUFFER, in case the cause for failure is unknown or plaform specific. - the server creates an invalid WlBuffer, marks it as failed and sends a ‘failed’ event to the client. The result of using this invalid WlBuffer as an argument in any request by the client is defined by the compositor implementation.

This takes the same arguments as a ‘create’ request, and obeys the same restrictions.

Parameters:	width (ArgumentType.Int) – base plane width in pixels height (ArgumentType.Int) – base plane height in pixels format (ArgumentType.Uint) – DRM_FORMAT code flags (ArgumentType.Uint) – see enum flags
Returns:	`WlBuffer` – id for the newly created `WlBuffer`

created(buffer)¶

Event – opcode 0 (attached to Proxy instance)

Buffer creation succeeded

This event indicates that the attempted buffer creation was successful. It provides the new WlBuffer referencing the dmabuf(s).

Upon receiving this event, the client should destroy the zlinux_dmabuf_params object.

Parameters:	buffer (`WlBuffer`) – the newly created `WlBuffer`

failed()¶

Event – opcode 1 (attached to Proxy instance)

Buffer creation failed

This event indicates that the attempted buffer creation has failed. It usually means that one of the dmabuf constraints has not been fulfilled.

Upon receiving this event, the client should destroy the zlinux_buffer_params object.

ZwpLinuxDmabufV1¶

class pywayland.protocol.linux_dmabuf_unstable_v1.ZwpLinuxDmabufV1¶

Factory for creating dmabuf-based wl_buffers

Following the interfaces from: https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt and the Linux DRM sub-system’s AddFb2 ioctl.

This interface offers ways to create generic dmabuf-based wl_buffers. Immediately after a client binds to this interface, the set of supported formats and format modifiers is sent with ‘format’ and ‘modifier’ events.

The following are required from clients:

Clients must ensure that either all data in the dma-buf is coherent for all subsequent read access or that coherency is correctly handled by the underlying kernel-side dma-buf implementation.
Don’t make any more attachments after sending the buffer to the compositor. Making more attachments later increases the risk of the compositor not being able to use (re-import) an existing dmabuf-based WlBuffer.

The underlying graphics stack must ensure the following:

The dmabuf file descriptors relayed to the server will stay valid for the whole lifetime of the WlBuffer. This means the server may at any time use those fds to import the dmabuf into any kernel sub-system that might accept it.

To create a WlBuffer from one or more dmabufs, a client creates a zwp_linux_dmabuf_params_v1 object with a ZwpLinuxDmabufV1.create_params() request. All planes required by the intended format are added with the ‘add’ request. Finally, a ‘create’ or ‘create_immed’ request is issued, which has the following outcome depending on the import success.

The ‘create’ request, - on success, triggers a ‘created’ event which provides the final WlBuffer to the client. - on failure, triggers a ‘failed’ event to convey that the server cannot use the dmabufs received from the client.

For the ‘create_immed’ request, - on success, the server immediately imports the added dmabufs to create a WlBuffer. No event is sent from the server in this case. - on failure, the server can choose to either: - terminate the client by raising a fatal error. - mark the WlBuffer as failed, and send a ‘failed’ event to the client. If the client uses a failed WlBuffer as an argument to any request, the behaviour is compositor implementation-defined.

Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Unbind the factory

Objects created through this interface, especially wl_buffers, will remain valid.

create_params()¶

Request – opcode 1 (attached to Resource instance)

Create a temporary object for buffer parameters

This temporary object is used to collect multiple dmabuf handles into a single batch to create a WlBuffer. It can only be used once and should be destroyed after a ‘created’ or ‘failed’ event has been received.

Returns:	`ZwpLinuxBufferParamsV1` – the new temporary

format(format)¶

Event – opcode 0 (attached to Proxy instance)

Supported buffer format

This event advertises one buffer format that the server supports. All the supported formats are advertised once when the client binds to this interface. A roundtrip after binding guarantees that the client has received all supported formats.

For the definition of the format codes, see the ZwpLinuxBufferParamsV1::create request.

Warning: the ‘format’ event is likely to be deprecated and replaced with the ‘modifier’ event introduced in ZwpLinuxDmabufV1 version 3, described below. Please refrain from using the information received from this event.

Parameters:	format (ArgumentType.Uint) – DRM_FORMAT code

modifier(format, modifier_hi, modifier_lo)¶

Event – opcode 1 (attached to Proxy instance)

Supported buffer format modifier

This event advertises the formats that the server supports, along with the modifiers supported for each format. All the supported modifiers for all the supported formats are advertised once when the client binds to this interface. A roundtrip after binding guarantees that the client has received all supported format-modifier pairs.

For legacy support, DRM_FORMAT_MOD_INVALID (that is, modifier_hi == 0x00ffffff and modifier_lo == 0xffffffff) is allowed in this event. It indicates that the server can support the format with an implicit modifier. When a plane has DRM_FORMAT_MOD_INVALID as its modifier, it is as if no explicit modifier is specified. The effective modifier will be derived from the dmabuf.

For the definition of the format and modifier codes, see the ZwpLinuxBufferParamsV1::create and ZwpLinuxBufferParamsV1::add requests.

Parameters:	format (ArgumentType.Uint) – DRM_FORMAT code modifier_hi (ArgumentType.Uint) – high 32 bits of layout modifier modifier_lo (ArgumentType.Uint) – low 32 bits of layout modifier

pointer_constraints_unstable_v1 Module¶

ZwpConfinedPointerV1¶

class pywayland.protocol.pointer_constraints_unstable_v1.ZwpConfinedPointerV1¶

Confined pointer object

The wp_confined_pointer interface represents a confined pointer state.

This object will send the event ‘confined’ when the confinement is activated. Whenever the confinement is activated, it is guaranteed that the surface the pointer is confined to will already have received pointer focus and that the pointer will be within the region passed to the request creating this object. It is up to the compositor to decide whether this requires some user interaction and if the pointer will warp to within the passed region if outside.

To unconfine the pointer, send the destroy request. This will also destroy the wp_confined_pointer object.

If the compositor decides to unconfine the pointer the unconfined event is sent. The wp_confined_pointer object is at this point defunct and should be destroyed.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the confined pointer object

Destroy the confined pointer object. If applicable, the compositor will unconfine the pointer.

set_region(region)¶

Request – opcode 1 (attached to Resource instance)

Set a new confine region

Set a new region used to confine the pointer.

The new confine region is double-buffered. The new confine region will only take effect when the associated surface gets its pending state applied. See WlSurface.commit() for details.

If the confinement is active when the new confinement region is applied and the pointer ends up outside of newly applied region, the pointer may warped to a position within the new confinement region. If warped, a WlPointer.motion() event will be emitted, but no wp_relative_pointer.relative_motion event.

The compositor may also, instead of using the new region, unconfine the pointer.

For details about the confine region, see wp_confined_pointer.

Parameters:	region (`WlRegion` or None) – region of surface

confined()¶

Event – opcode 0 (attached to Proxy instance)

Pointer confined

Notification that the pointer confinement of the seat’s pointer is activated.

unconfined()¶

Event – opcode 1 (attached to Proxy instance)

Pointer unconfined

Notification that the pointer confinement of the seat’s pointer is no longer active. If this is a oneshot pointer confinement (see wp_pointer_constraints.lifetime) this object is now defunct and should be destroyed. If this is a persistent pointer confinement (see wp_pointer_constraints.lifetime) this pointer confinement may again reactivate in the future.

ZwpPointerConstraintsV1¶

class pywayland.protocol.pointer_constraints_unstable_v1.ZwpPointerConstraintsV1¶

Constrain the movement of a pointer

The global interface exposing pointer constraining functionality. It exposes two requests: lock_pointer for locking the pointer to its position, and confine_pointer for locking the pointer to a region.

The lock_pointer and confine_pointer requests create the objects wp_locked_pointer and wp_confined_pointer respectively, and the client can use these objects to interact with the lock.

For any surface, only one lock or confinement may be active across all WlPointer objects of the same seat. If a lock or confinement is requested when another lock or confinement is active or requested on the same surface and with any of the WlPointer objects of the same seat, an ‘already_constrained’ error will be raised.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the pointer constraints manager object

Used by the client to notify the server that it will no longer use this pointer constraints object.

lock_pointer(surface, pointer, region, lifetime)¶

Request – opcode 1 (attached to Resource instance)

Lock pointer to a position

The lock_pointer request lets the client request to disable movements of the virtual pointer (i.e. the cursor), effectively locking the pointer to a position. This request may not take effect immediately; in the future, when the compositor deems implementation-specific constraints are satisfied, the pointer lock will be activated and the compositor sends a locked event.

The protocol provides no guarantee that the constraints are ever satisfied, and does not require the compositor to send an error if the constraints cannot ever be satisfied. It is thus possible to request a lock that will never activate.

There may not be another pointer constraint of any kind requested or active on the surface for any of the WlPointer objects of the seat of the passed pointer when requesting a lock. If there is, an error will be raised. See general pointer lock documentation for more details.

The intersection of the region passed with this request and the input region of the surface is used to determine where the pointer must be in order for the lock to activate. It is up to the compositor whether to warp the pointer or require some kind of user interaction for the lock to activate. If the region is null the surface input region is used.

A surface may receive pointer focus without the lock being activated.

The request creates a new object wp_locked_pointer which is used to interact with the lock as well as receive updates about its state. See the the description of wp_locked_pointer for further information.

Note that while a pointer is locked, the WlPointer objects of the corresponding seat will not emit any WlPointer.motion() events, but relative motion events will still be emitted via wp_relative_pointer objects of the same seat. WlPointer.axis() and WlPointer.button() events are unaffected.

Parameters:	surface (`WlSurface`) – surface to lock pointer to pointer (`WlPointer`) – the pointer that should be locked region (`WlRegion` or None) – region of surface lifetime (ArgumentType.Uint) – lock lifetime
Returns:	`ZwpLockedPointerV1`

confine_pointer(surface, pointer, region, lifetime)¶

Request – opcode 2 (attached to Resource instance)

Confine pointer to a region

The confine_pointer request lets the client request to confine the pointer cursor to a given region. This request may not take effect immediately; in the future, when the compositor deems implementation- specific constraints are satisfied, the pointer confinement will be activated and the compositor sends a confined event.

The intersection of the region passed with this request and the input region of the surface is used to determine where the pointer must be in order for the confinement to activate. It is up to the compositor whether to warp the pointer or require some kind of user interaction for the confinement to activate. If the region is null the surface input region is used.

The request will create a new object wp_confined_pointer which is used to interact with the confinement as well as receive updates about its state. See the the description of wp_confined_pointer for further information.

Parameters:	surface (`WlSurface`) – surface to lock pointer to pointer (`WlPointer`) – the pointer that should be confined region (`WlRegion` or None) – region of surface lifetime (ArgumentType.Uint) – confinement lifetime
Returns:	`ZwpConfinedPointerV1`

ZwpLockedPointerV1¶

class pywayland.protocol.pointer_constraints_unstable_v1.ZwpLockedPointerV1¶

Receive relative pointer motion events

The wp_locked_pointer interface represents a locked pointer state.

While the lock of this object is active, the WlPointer objects of the associated seat will not emit any WlPointer.motion() events.

This object will send the event ‘locked’ when the lock is activated. Whenever the lock is activated, it is guaranteed that the locked surface will already have received pointer focus and that the pointer will be within the region passed to the request creating this object.

To unlock the pointer, send the destroy request. This will also destroy the wp_locked_pointer object.

If the compositor decides to unlock the pointer the unlocked event is sent. See wp_locked_pointer.unlock for details.

When unlocking, the compositor may warp the cursor position to the set cursor position hint. If it does, it will not result in any relative motion events emitted via wp_relative_pointer.

If the surface the lock was requested on is destroyed and the lock is not yet activated, the wp_locked_pointer object is now defunct and must be destroyed.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the locked pointer object

Destroy the locked pointer object. If applicable, the compositor will unlock the pointer.

set_cursor_position_hint(surface_x, surface_y)¶

Request – opcode 1 (attached to Resource instance)

Set the pointer cursor position hint

Set the cursor position hint relative to the top left corner of the surface.

If the client is drawing its own cursor, it should update the position hint to the position of its own cursor. A compositor may use this information to warp the pointer upon unlock in order to avoid pointer jumps.

The cursor position hint is double buffered. The new hint will only take effect when the associated surface gets it pending state applied. See WlSurface.commit() for details.

Parameters:	surface_x (ArgumentType.Fixed) – surface-local x coordinate surface_y (ArgumentType.Fixed) – surface-local y coordinate

set_region(region)¶

Request – opcode 2 (attached to Resource instance)

Set a new lock region

Set a new region used to lock the pointer.

The new lock region is double-buffered. The new lock region will only take effect when the associated surface gets its pending state applied. See WlSurface.commit() for details.

For details about the lock region, see wp_locked_pointer.

Parameters:	region (`WlRegion` or None) – region of surface

locked()¶

Event – opcode 0 (attached to Proxy instance)

Lock activation event

Notification that the pointer lock of the seat’s pointer is activated.

unlocked()¶

Event – opcode 1 (attached to Proxy instance)

Lock deactivation event

Notification that the pointer lock of the seat’s pointer is no longer active. If this is a oneshot pointer lock (see wp_pointer_constraints.lifetime) this object is now defunct and should be destroyed. If this is a persistent pointer lock (see wp_pointer_constraints.lifetime) this pointer lock may again reactivate in the future.

pointer_gestures_unstable_v1 Module¶

ZwpPointerGestureSwipeV1¶

class pywayland.protocol.pointer_gestures_unstable_v1.ZwpPointerGestureSwipeV1¶

A swipe gesture object

A swipe gesture object notifies a client about a multi-finger swipe gesture detected on an indirect input device such as a touchpad. The gesture is usually initiated by multiple fingers moving in the same direction but once initiated the direction may change. The precise conditions of when such a gesture is detected are implementation-dependent.

A gesture consists of three stages: begin, update (optional) and end. There cannot be multiple simultaneous pinch or swipe gestures on a same pointer/seat, how compositors prevent these situations is implementation- dependent.

A gesture may be cancelled by the compositor or the hardware. Clients should not consider performing permanent or irreversible actions until the end of a gesture has been received.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the pointer swipe gesture object

begin(serial, time, surface, fingers)¶

Event – opcode 0 (attached to Proxy instance)

Multi-finger swipe begin

This event is sent when a multi-finger swipe gesture is detected on the device.

Parameters:	serial (ArgumentType.Uint) – time (ArgumentType.Uint) – timestamp with millisecond granularity surface (`WlSurface`) – fingers (ArgumentType.Uint) – number of fingers

update(time, dx, dy)¶

Event – opcode 1 (attached to Proxy instance)

Multi-finger swipe motion

This event is sent when a multi-finger swipe gesture changes the position of the logical center.

The dx and dy coordinates are relative coordinates of the logical center of the gesture compared to the previous event.

Parameters:	time (ArgumentType.Uint) – timestamp with millisecond granularity dx (ArgumentType.Fixed) – delta x coordinate in surface coordinate space dy (ArgumentType.Fixed) – delta y coordinate in surface coordinate space

end(serial, time, cancelled)¶

Event – opcode 2 (attached to Proxy instance)

Multi-finger swipe end

This event is sent when a multi-finger swipe gesture ceases to be valid. This may happen when one or more fingers are lifted or the gesture is cancelled.

When a gesture is cancelled, the client should undo state changes caused by this gesture. What causes a gesture to be cancelled is implementation-dependent.

Parameters:	serial (ArgumentType.Uint) – time (ArgumentType.Uint) – timestamp with millisecond granularity cancelled (ArgumentType.Int) – 1 if the gesture was cancelled, 0 otherwise

ZwpPointerGesturePinchV1¶

class pywayland.protocol.pointer_gestures_unstable_v1.ZwpPointerGesturePinchV1¶

A pinch gesture object

A pinch gesture object notifies a client about a multi-finger pinch gesture detected on an indirect input device such as a touchpad. The gesture is usually initiated by multiple fingers moving towards each other or away from each other, or by two or more fingers rotating around a logical center of gravity. The precise conditions of when such a gesture is detected are implementation-dependent.

A gesture consists of three stages: begin, update (optional) and end. There cannot be multiple simultaneous pinch or swipe gestures on a same pointer/seat, how compositors prevent these situations is implementation- dependent.

A gesture may be cancelled by the compositor or the hardware. Clients should not consider performing permanent or irreversible actions until the end of a gesture has been received.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the pinch gesture object

begin(serial, time, surface, fingers)¶

Event – opcode 0 (attached to Proxy instance)

Multi-finger pinch begin

This event is sent when a multi-finger pinch gesture is detected on the device.

Parameters:	serial (ArgumentType.Uint) – time (ArgumentType.Uint) – timestamp with millisecond granularity surface (`WlSurface`) – fingers (ArgumentType.Uint) – number of fingers

update(time, dx, dy, scale, rotation)¶

Event – opcode 1 (attached to Proxy instance)

Multi-finger pinch motion

This event is sent when a multi-finger pinch gesture changes the position of the logical center, the rotation or the relative scale.

The dx and dy coordinates are relative coordinates in the surface coordinate space of the logical center of the gesture.

The scale factor is an absolute scale compared to the pointer_gesture_pinch.begin event, e.g. a scale of 2 means the fingers are now twice as far apart as on pointer_gesture_pinch.begin.

The rotation is the relative angle in degrees clockwise compared to the previous pointer_gesture_pinch.begin or pointer_gesture_pinch.update event.

Parameters:	time (ArgumentType.Uint) – timestamp with millisecond granularity dx (ArgumentType.Fixed) – delta x coordinate in surface coordinate space dy (ArgumentType.Fixed) – delta y coordinate in surface coordinate space scale (ArgumentType.Fixed) – scale relative to the initial finger position rotation (ArgumentType.Fixed) – angle in degrees cw relative to the previous event

end(serial, time, cancelled)¶

Event – opcode 2 (attached to Proxy instance)

Multi-finger pinch end

This event is sent when a multi-finger pinch gesture ceases to be valid. This may happen when one or more fingers are lifted or the gesture is cancelled.

When a gesture is cancelled, the client should undo state changes caused by this gesture. What causes a gesture to be cancelled is implementation-dependent.

Parameters:	serial (ArgumentType.Uint) – time (ArgumentType.Uint) – timestamp with millisecond granularity cancelled (ArgumentType.Int) – 1 if the gesture was cancelled, 0 otherwise

ZwpPointerGesturesV1¶

class pywayland.protocol.pointer_gestures_unstable_v1.ZwpPointerGesturesV1¶

Touchpad gestures

A global interface to provide semantic touchpad gestures for a given pointer.

Two gestures are currently supported: swipe and zoom/rotate. All gestures follow a three-stage cycle: begin, update, end and are identified by a unique id.

Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.

get_swipe_gesture(pointer)¶

Request – opcode 0 (attached to Resource instance)

Get swipe gesture

Create a swipe gesture object. See the wl_pointer_gesture_swipe interface for details.

Parameters:	pointer (`WlPointer`) –
Returns:	`ZwpPointerGestureSwipeV1`

get_pinch_gesture(pointer)¶

Request – opcode 1 (attached to Resource instance)

Get pinch gesture

Create a pinch gesture object. See the wl_pointer_gesture_pinch interface for details.

Parameters:	pointer (`WlPointer`) –
Returns:	`ZwpPointerGesturePinchV1`

release()¶

Request – opcode 2 (attached to Resource instance)

Destroy the pointer gesture object

Destroy the pointer gesture object. Swipe and pinch objects created via this gesture object remain valid.

presentation_time Module¶

WpPresentation¶

class pywayland.protocol.presentation_time.WpPresentation¶

Timed presentation related WlSurface requests

The main feature of this interface is accurate presentation timing feedback to ensure smooth video playback while maintaining audio/video synchronization. Some features use the concept of a presentation clock, which is defined in the presentation.clock_id event.

A content update for a WlSurface is submitted by a WlSurface.commit() request. Request ‘feedback’ associates with the WlSurface.commit() and provides feedback on the content update, particularly the final realized presentation time.

When the final realized presentation time is available, e.g. after a framebuffer flip completes, the requested presentation_feedback.presented events are sent. The final presentation time can differ from the compositor’s predicted display update time and the update’s target time, especially when the compositor misses its target vertical blanking period.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Unbind from the presentation interface

Informs the server that the client will no longer be using this protocol object. Existing objects created by this object are not affected.

feedback(surface)¶

Request – opcode 1 (attached to Resource instance)

Request presentation feedback information

Request presentation feedback for the current content submission on the given surface. This creates a new presentation_feedback object, which will deliver the feedback information once. If multiple presentation_feedback objects are created for the same submission, they will all deliver the same information.

For details on what information is returned, see the presentation_feedback interface.

Parameters:	surface (`WlSurface`) – target surface
Returns:	`WpPresentationFeedback` – new feedback object

clock_id(clk_id)¶

Event – opcode 0 (attached to Proxy instance)

Clock id for timestamps

This event tells the client in which clock domain the compositor interprets the timestamps used by the presentation extension. This clock is called the presentation clock.

The compositor sends this event when the client binds to the presentation interface. The presentation clock does not change during the lifetime of the client connection.

The clock identifier is platform dependent. On Linux/glibc, the identifier value is one of the clockid_t values accepted by clock_gettime(). clock_gettime() is defined by POSIX.1-2001.

Timestamps in this clock domain are expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples, each component being an unsigned 32-bit value. Whole seconds are in tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo, and the additional fractional part in tv_nsec as nanoseconds. Hence, for valid timestamps tv_nsec must be in [0, 999999999].

Note that clock_id applies only to the presentation clock, and implies nothing about e.g. the timestamps used in the Wayland core protocol input events.

Compositors should prefer a clock which does not jump and is not slewed e.g. by NTP. The absolute value of the clock is irrelevant. Precision of one millisecond or better is recommended. Clients must be able to query the current clock value directly, not by asking the compositor.

Parameters:	clk_id (ArgumentType.Uint) – platform clock identifier

WpPresentationFeedback¶

class pywayland.protocol.presentation_time.WpPresentationFeedback¶

Presentation time feedback event

A presentation_feedback object returns an indication that a WlSurface content update has become visible to the user. One object corresponds to one content update submission (WlSurface.commit()). There are two possible outcomes: the content update is presented to the user, and a presentation timestamp delivered; or, the user did not see the content update because it was superseded or its surface destroyed, and the content update is discarded.

Once a presentation_feedback object has delivered a ‘presented’ or ‘discarded’ event it is automatically destroyed.

sync_output(output)¶

Event – opcode 0 (attached to Proxy instance)

Presentation synchronized to this output

As presentation can be synchronized to only one output at a time, this event tells which output it was. This event is only sent prior to the presented event.

As clients may bind to the same global WlOutput multiple times, this event is sent for each bound instance that matches the synchronized output. If a client has not bound to the right WlOutput global at all, this event is not sent.

Parameters:	output (`WlOutput`) – presentation output

presented(tv_sec_hi, tv_sec_lo, tv_nsec, refresh, seq_hi, seq_lo, flags)¶

Event – opcode 1 (attached to Proxy instance)

The content update was displayed

The associated content update was displayed to the user at the indicated time (tv_sec_hi/lo, tv_nsec). For the interpretation of the timestamp, see presentation.clock_id event.

The timestamp corresponds to the time when the content update turned into light the first time on the surface’s main output. Compositors may approximate this from the framebuffer flip completion events from the system, and the latency of the physical display path if known.

This event is preceded by all related sync_output events telling which output’s refresh cycle the feedback corresponds to, i.e. the main output for the surface. Compositors are recommended to choose the output containing the largest part of the WlSurface, or keeping the output they previously chose. Having a stable presentation output association helps clients predict future output refreshes (vblank).

The ‘refresh’ argument gives the compositor’s prediction of how many nanoseconds after tv_sec, tv_nsec the very next output refresh may occur. This is to further aid clients in predicting future refreshes, i.e., estimating the timestamps targeting the next few vblanks. If such prediction cannot usefully be done, the argument is zero.

If the output does not have a constant refresh rate, explicit video mode switches excluded, then the refresh argument must be zero.

The 64-bit value combined from seq_hi and seq_lo is the value of the output’s vertical retrace counter when the content update was first scanned out to the display. This value must be compatible with the definition of MSC in GLX_OML_sync_control specification. Note, that if the display path has a non-zero latency, the time instant specified by this counter may differ from the timestamp’s.

If the output does not have a concept of vertical retrace or a refresh cycle, or the output device is self-refreshing without a way to query the refresh count, then the arguments seq_hi and seq_lo must be zero.

Parameters:

tv_sec_hi (ArgumentType.Uint) – high 32 bits of the seconds part of the presentation timestamp
tv_sec_lo (ArgumentType.Uint) – low 32 bits of the seconds part of the presentation timestamp
tv_nsec (ArgumentType.Uint) – nanoseconds part of the presentation timestamp
refresh (ArgumentType.Uint) – nanoseconds till next refresh
seq_hi (ArgumentType.Uint) – high 32 bits of refresh counter
seq_lo (ArgumentType.Uint) – low 32 bits of refresh counter
flags (ArgumentType.Uint) – combination of ‘kind’ values

discarded()¶

Event – opcode 2 (attached to Proxy instance)

The content update was not displayed

The content update was never displayed to the user.

relative_pointer_unstable_v1 Module¶

ZwpRelativePointerV1¶

class pywayland.protocol.relative_pointer_unstable_v1.ZwpRelativePointerV1¶

Relative pointer object

A wp_relative_pointer object is an extension to the WlPointer interface used for emitting relative pointer events. It shares the same focus as WlPointer objects of the same seat and will only emit events when it has focus.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Release the relative pointer object

relative_motion(utime_hi, utime_lo, dx, dy, dx_unaccel, dy_unaccel)¶

Event – opcode 0 (attached to Proxy instance)

Relative pointer motion

Relative x/y pointer motion from the pointer of the seat associated with this object.

A relative motion is in the same dimension as regular WlPointer motion events, except they do not represent an absolute position. For example, moving a pointer from (x, y) to (x’, y’) would have the equivalent relative motion (x’ - x, y’ - y). If a pointer motion caused the absolute pointer position to be clipped by for example the edge of the monitor, the relative motion is unaffected by the clipping and will represent the unclipped motion.

This event also contains non-accelerated motion deltas. The non- accelerated delta is, when applicable, the regular pointer motion delta as it was before having applied motion acceleration and other transformations such as normalization.

Note that the non-accelerated delta does not represent ‘raw’ events as they were read from some device. Pointer motion acceleration is device- and configuration-specific and non-accelerated deltas and accelerated deltas may have the same value on some devices.

Relative motions are not coupled to WlPointer.motion() events, and can be sent in combination with such events, but also independently. There may also be scenarios where WlPointer.motion() is sent, but there is no relative motion. The order of an absolute and relative motion event originating from the same physical motion is not guaranteed.

If the client needs button events or focus state, it can receive them from a WlPointer object of the same seat that the wp_relative_pointer object is associated with.

Parameters:

utime_hi (ArgumentType.Uint) – high 32 bits of a 64 bit timestamp with microsecond granularity
utime_lo (ArgumentType.Uint) – low 32 bits of a 64 bit timestamp with microsecond granularity
dx (ArgumentType.Fixed) – the x component of the motion vector
dy (ArgumentType.Fixed) – the y component of the motion vector
dx_unaccel (ArgumentType.Fixed) – the x component of the unaccelerated motion vector
dy_unaccel (ArgumentType.Fixed) – the y component of the unaccelerated motion vector

ZwpRelativePointerManagerV1¶

class pywayland.protocol.relative_pointer_unstable_v1.ZwpRelativePointerManagerV1¶

Get relative pointer objects

A global interface used for getting the relative pointer object for a given pointer.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the relative pointer manager object

Used by the client to notify the server that it will no longer use this relative pointer manager object.

get_relative_pointer(pointer)¶

Request – opcode 1 (attached to Resource instance)

Get a relative pointer object

Create a relative pointer interface given a WlPointer object. See the wp_relative_pointer interface for more details.

Parameters:	pointer (`WlPointer`) –
Returns:	`ZwpRelativePointerV1`

tablet_unstable_v1 Module¶

ZwpTabletSeatV1¶

class pywayland.protocol.tablet_unstable_v1.ZwpTabletSeatV1¶

Controller object for graphic tablet devices of a seat

An object that provides access to the graphics tablets available on this seat. After binding to this interface, the compositor sends a set of wp_tablet_seat.tablet_added and wp_tablet_seat.tool_added events.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Release the memory for the tablet seat object

Destroy the wp_tablet_seat object. Objects created from this object are unaffected and should be destroyed separately.

tablet_added(id)¶

Event – opcode 0 (attached to Proxy instance)

New device notification

This event is sent whenever a new tablet becomes available on this seat. This event only provides the object id of the tablet, any static information about the tablet (device name, vid/pid, etc.) is sent through the wp_tablet interface.

Parameters:	id (`ZwpTabletV1`) – the newly added graphics tablet

tool_added(id)¶

Event – opcode 1 (attached to Proxy instance)

A new tool has been used with a tablet

This event is sent whenever a tool that has not previously been used with a tablet comes into use. This event only provides the object id of the tool; any static information about the tool (capabilities, type, etc.) is sent through the wp_tablet_tool interface.

Parameters:	id (`ZwpTabletToolV1`) – the newly added tablet tool

ZwpTabletV1¶

class pywayland.protocol.tablet_unstable_v1.ZwpTabletV1¶

Graphics tablet device

The wp_tablet interface represents one graphics tablet device. The tablet interface itself does not generate events; all events are generated by wp_tablet_tool objects when in proximity above a tablet.

A tablet has a number of static characteristics, e.g. device name and pid/vid. These capabilities are sent in an event sequence after the wp_tablet_seat.tablet_added event. This initial event sequence is terminated by a wp_tablet.done event.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the tablet object

This destroys the client’s resource for this tablet object.

name(name)¶

Event – opcode 0 (attached to Proxy instance)

Tablet device name

This event is sent in the initial burst of events before the wp_tablet.done event.

Parameters:	name (ArgumentType.String) – the device name

id(vid, pid)¶

Event – opcode 1 (attached to Proxy instance)

Tablet device usb vendor/product id

This event is sent in the initial burst of events before the wp_tablet.done event.

Parameters:	vid (ArgumentType.Uint) – USB vendor id pid (ArgumentType.Uint) – USB product id

path(path)¶

Event – opcode 2 (attached to Proxy instance)

Path to the device

A system-specific device path that indicates which device is behind this wp_tablet. This information may be used to gather additional information about the device, e.g. through libwacom.

A device may have more than one device path. If so, multiple wp_tablet.path events are sent. A device may be emulated and not have a device path, and in that case this event will not be sent.

The format of the path is unspecified, it may be a device node, a sysfs path, or some other identifier. It is up to the client to identify the string provided.

This event is sent in the initial burst of events before the wp_tablet.done event.

Parameters:	path (ArgumentType.String) – path to local device

done()¶

Event – opcode 3 (attached to Proxy instance)

Tablet description events sequence complete

This event is sent immediately to signal the end of the initial burst of descriptive events. A client may consider the static description of the tablet to be complete and finalize initialization of the tablet.

removed()¶

Event – opcode 4 (attached to Proxy instance)

Tablet removed event

Sent when the tablet has been removed from the system. When a tablet is removed, some tools may be removed.

When this event is received, the client must wp_tablet.destroy the object.

ZwpTabletManagerV1¶

class pywayland.protocol.tablet_unstable_v1.ZwpTabletManagerV1¶

Controller object for graphic tablet devices

An object that provides access to the graphics tablets available on this system. All tablets are associated with a seat, to get access to the actual tablets, use wp_tablet_manager.get_tablet_seat.

get_tablet_seat(seat)¶

Request – opcode 0 (attached to Resource instance)

Get the tablet seat

Get the wp_tablet_seat object for the given seat. This object provides access to all graphics tablets in this seat.

Parameters:	seat (`WlSeat`) – The `WlSeat` object to retrieve the tablets for
Returns:	`ZwpTabletSeatV1`

destroy()¶

Request – opcode 1 (attached to Resource instance)

Release the memory for the tablet manager object

Destroy the wp_tablet_manager object. Objects created from this object are unaffected and should be destroyed separately.

ZwpTabletToolV1¶

class pywayland.protocol.tablet_unstable_v1.ZwpTabletToolV1¶

A physical tablet tool

An object that represents a physical tool that has been, or is currently in use with a tablet in this seat. Each wp_tablet_tool object stays valid until the client destroys it; the compositor reuses the wp_tablet_tool object to indicate that the object’s respective physical tool has come into proximity of a tablet again.

A wp_tablet_tool object’s relation to a physical tool depends on the tablet’s ability to report serial numbers. If the tablet supports this capability, then the object represents a specific physical tool and can be identified even when used on multiple tablets.

A tablet tool has a number of static characteristics, e.g. tool type, hardware_serial and capabilities. These capabilities are sent in an event sequence after the wp_tablet_seat.tool_added event before any actual events from this tool. This initial event sequence is terminated by a wp_tablet_tool.done event.

Tablet tool events are grouped by wp_tablet_tool.frame events. Any events received before a wp_tablet_tool.frame event should be considered part of the same hardware state change.

set_cursor(serial, surface, hotspot_x, hotspot_y)¶

Request – opcode 0 (attached to Resource instance)

Set the tablet tool’s surface

Sets the surface of the cursor used for this tool on the given tablet. This request only takes effect if the tool is in proximity of 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 cursor image is hidden.

The parameters hotspot_x and hotspot_y define the position of the pointer surface relative to the pointer location. Its top-left corner is always at (x, y) - (hotspot_x, hotspot_y), where (x, y) are the coordinates of the pointer location, in surface-local coordinates.

On surface.attach requests to the pointer surface, hotspot_x and hotspot_y are decremented by the x and y parameters passed to the request. Attach must be confirmed by 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 current and pending input regions of the WlSurface are cleared, and WlSurface.set_input_region() is ignored until the WlSurface is no longer used as the cursor. When the use as a cursor ends, the current and pending input regions become undefined, and the WlSurface is unmapped.

This request gives the surface the role of a cursor. The role assigned by this request is the same as assigned by WlPointer.set_cursor() meaning the same surface can be used both as a WlPointer cursor and a wp_tablet cursor. If the surface already has another role, it raises a protocol error. The surface may be used on multiple tablets and across multiple seats.

Parameters:	serial (ArgumentType.Uint) – serial of the enter event surface (`WlSurface` or None) – hotspot_x (ArgumentType.Int) – surface-local x coordinate hotspot_y (ArgumentType.Int) – surface-local y coordinate

destroy()¶

Request – opcode 1 (attached to Resource instance)

Destroy the tool object

This destroys the client’s resource for this tool object.

type(tool_type)¶

Event – opcode 0 (attached to Proxy instance)

Tool type

The tool type is the high-level type of the tool and usually decides the interaction expected from this tool.

This event is sent in the initial burst of events before the wp_tablet_tool.done event.

Parameters:	tool_type (ArgumentType.Uint) – the physical tool type

hardware_serial(hardware_serial_hi, hardware_serial_lo)¶

Event – opcode 1 (attached to Proxy instance)

Unique hardware serial number of the tool

If the physical tool can be identified by a unique 64-bit serial number, this event notifies the client of this serial number.

If multiple tablets are available in the same seat and the tool is uniquely identifiable by the serial number, that tool may move between tablets.

Otherwise, if the tool has no serial number and this event is missing, the tool is tied to the tablet it first comes into proximity with. Even if the physical tool is used on multiple tablets, separate wp_tablet_tool objects will be created, one per tablet.

This event is sent in the initial burst of events before the wp_tablet_tool.done event.

Parameters:	hardware_serial_hi (ArgumentType.Uint) – the unique serial number of the tool, most significant bits hardware_serial_lo (ArgumentType.Uint) – the unique serial number of the tool, least significant bits

hardware_id_wacom(hardware_id_hi, hardware_id_lo)¶

Event – opcode 2 (attached to Proxy instance)

Hardware id notification in wacom’s format

This event notifies the client of a hardware id available on this tool.

The hardware id is a device-specific 64-bit id that provides extra information about the tool in use, beyond the wl_tool.type enumeration. The format of the id is specific to tablets made by Wacom Inc. For example, the hardware id of a Wacom Grip Pen (a stylus) is 0x802.

This event is sent in the initial burst of events before the wp_tablet_tool.done event.

Parameters:	hardware_id_hi (ArgumentType.Uint) – the hardware id, most significant bits hardware_id_lo (ArgumentType.Uint) – the hardware id, least significant bits

capability(capability)¶

Event – opcode 3 (attached to Proxy instance)

Tool capability notification

This event notifies the client of any capabilities of this tool, beyond the main set of x/y axes and tip up/down detection.

One event is sent for each extra capability available on this tool.

This event is sent in the initial burst of events before the wp_tablet_tool.done event.

Parameters:	capability (ArgumentType.Uint) – the capability

done()¶

Event – opcode 4 (attached to Proxy instance)

Tool description events sequence complete

This event signals the end of the initial burst of descriptive events. A client may consider the static description of the tool to be complete and finalize initialization of the tool.

removed()¶

Event – opcode 5 (attached to Proxy instance)

Tool removed

This event is sent when the tool is removed from the system and will send no further events. Should the physical tool come back into proximity later, a new wp_tablet_tool object will be created.

It is compositor-dependent when a tool is removed. A compositor may remove a tool on proximity out, tablet removal or any other reason. A compositor may also keep a tool alive until shutdown.

If the tool is currently in proximity, a proximity_out event will be sent before the removed event. See wp_tablet_tool.proximity_out for the handling of any buttons logically down.

When this event is received, the client must wp_tablet_tool.destroy the object.

proximity_in(serial, tablet, surface)¶

Event – opcode 6 (attached to Proxy instance)

Proximity in event

Notification that this tool is focused on a certain surface.

This event can be received when the tool has moved from one surface to another, or when the tool has come back into proximity above the surface.

If any button is logically down when the tool comes into proximity, the respective button event is sent after the proximity_in event but within the same frame as the proximity_in event.

Parameters:	serial (ArgumentType.Uint) – tablet (`ZwpTabletV1`) – The tablet the tool is in proximity of surface (`WlSurface`) – The current surface the tablet tool is over

proximity_out()¶

Event – opcode 7 (attached to Proxy instance)

Proximity out event

Notification that this tool has either left proximity, or is no longer focused on a certain surface.

When the tablet tool leaves proximity of the tablet, button release events are sent for each button that was held down at the time of leaving proximity. These events are sent before the proximity_out event but within the same wp_tablet.frame.

If the tool stays within proximity of the tablet, but the focus changes from one surface to another, a button release event may not be sent until the button is actually released or the tool leaves the proximity of the tablet.

down(serial)¶

Event – opcode 8 (attached to Proxy instance)

Tablet tool is making contact

Sent whenever the tablet tool comes in contact with the surface of the tablet.

If the tool is already in contact with the tablet when entering the input region, the client owning said region will receive a wp_tablet.proximity_in event, followed by a wp_tablet.down event and a wp_tablet.frame event.

Note that this event describes logical contact, not physical contact. On some devices, a compositor may not consider a tool in logical contact until a minimum physical pressure threshold is exceeded.

Parameters:	serial (ArgumentType.Uint) –

up()¶

Event – opcode 9 (attached to Proxy instance)

Tablet tool is no longer making contact

Sent whenever the tablet tool stops making contact with the surface of the tablet, or when the tablet tool moves out of the input region and the compositor grab (if any) is dismissed.

If the tablet tool moves out of the input region while in contact with the surface of the tablet and the compositor does not have an ongoing grab on the surface, the client owning said region will receive a wp_tablet.up event, followed by a wp_tablet.proximity_out event and a wp_tablet.frame event. If the compositor has an ongoing grab on this device, this event sequence is sent whenever the grab is dismissed in the future.

Note that this event describes logical contact, not physical contact. On some devices, a compositor may not consider a tool out of logical contact until physical pressure falls below a specific threshold.

motion(x, y)¶

Event – opcode 10 (attached to Proxy instance)

Motion event

Sent whenever a tablet tool moves.

Parameters:	x (ArgumentType.Fixed) – surface-local x coordinate y (ArgumentType.Fixed) – surface-local y coordinate

pressure(pressure)¶

Event – opcode 11 (attached to Proxy instance)

Pressure change event

Sent whenever the pressure axis on a tool changes. The value of this event is normalized to a value between 0 and 65535.

Note that pressure may be nonzero even when a tool is not in logical contact. See the down and up events for more details.

Parameters:	pressure (ArgumentType.Uint) – The current pressure value

distance(distance)¶

Event – opcode 12 (attached to Proxy instance)

Distance change event

Sent whenever the distance axis on a tool changes. The value of this event is normalized to a value between 0 and 65535.

Note that distance may be nonzero even when a tool is not in logical contact. See the down and up events for more details.

Parameters:	distance (ArgumentType.Uint) – The current distance value

tilt(tilt_x, tilt_y)¶

Event – opcode 13 (attached to Proxy instance)

Tilt change event

Sent whenever one or both of the tilt axes on a tool change. Each tilt value is in 0.01 of a degree, relative to the z-axis of the tablet. The angle is positive when the top of a tool tilts along the positive x or y axis.

Parameters:	tilt_x (ArgumentType.Int) – The current value of the X tilt axis tilt_y (ArgumentType.Int) – The current value of the Y tilt axis

rotation(degrees)¶

Event – opcode 14 (attached to Proxy instance)

Z-rotation change event

Sent whenever the z-rotation axis on the tool changes. The rotation value is in 0.01 of a degree clockwise from the tool’s logical neutral position.

Parameters:	degrees (ArgumentType.Int) – The current rotation of the Z axis

slider(position)¶

Event – opcode 15 (attached to Proxy instance)

Slider position change event

Sent whenever the slider position on the tool changes. The value is normalized between -65535 and 65535, with 0 as the logical neutral position of the slider.

The slider is available on e.g. the Wacom Airbrush tool.

Parameters:	position (ArgumentType.Int) – The current position of slider

wheel(degrees, clicks)¶

Event – opcode 16 (attached to Proxy instance)

Wheel delta event

Sent whenever the wheel on the tool emits an event. This event contains two values for the same axis change. The degrees value is in 0.01 of a degree in the same orientation as the WlPointer.vertical_scroll() axis. The clicks value is in discrete logical clicks of the mouse wheel. This value may be zero if the movement of the wheel was less than one logical click.

Clients should choose either value and avoid mixing degrees and clicks. The compositor may accumulate values smaller than a logical click and emulate click events when a certain threshold is met. Thus, wl_tablet_tool.wheel events with non-zero clicks values may have different degrees values.

Parameters:	degrees (ArgumentType.Int) – The wheel delta in 0.01 of a degree clicks (ArgumentType.Int) – The wheel delta in discrete clicks

button(serial, button, state)¶

Event – opcode 17 (attached to Proxy instance)

Button event

Sent whenever a button on the tool is pressed or released.

If a button is held down when the tool moves in or out of proximity, button events are generated by the compositor. See wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for details.

Parameters:	serial (ArgumentType.Uint) – button (ArgumentType.Uint) – The button whose state has changed state (ArgumentType.Uint) – Whether the button was pressed or released

frame(time)¶

Event – opcode 18 (attached to Proxy instance)

Frame event

Marks the end of a series of axis and/or button updates from the tablet. The Wayland protocol requires axis updates to be sent sequentially, however all events within a frame should be considered one hardware event.

Parameters:	time (ArgumentType.Uint) – The time of the event with millisecond granularity

tablet_unstable_v2 Module¶

ZwpTabletPadRingV2¶

class pywayland.protocol.tablet_unstable_v2.ZwpTabletPadRingV2¶

Pad ring

A circular interaction area, such as the touch ring on the Wacom Intuos Pro series tablets.

Events on a ring are logically grouped by the wl_tablet_pad_ring.frame event.

set_feedback(description, serial)¶

Request – opcode 0 (attached to Resource instance)

Set compositor feedback

Request that the compositor use the provided feedback string associated with this ring. This request should be issued immediately after a wp_tablet_pad_group.mode_switch event from the corresponding group is received, or whenever the ring is mapped to a different action. See wp_tablet_pad_group.mode_switch for more details.

Clients are encouraged to provide context-aware descriptions for the actions associated with the ring; compositors may use this information to offer visual feedback about the button layout (eg. on-screen displays).

The provided string ‘description’ is a UTF-8 encoded string to be associated with this ring, and is considered user-visible; general internationalization rules apply.

The serial argument will be that of the last wp_tablet_pad_group.mode_switch event received for the group of this ring. Requests providing other serials than the most recent one will be ignored.

Parameters:	description (ArgumentType.String) – ring description serial (ArgumentType.Uint) – serial of the mode switch event

destroy()¶

Request – opcode 1 (attached to Resource instance)

Destroy the ring object

This destroys the client’s resource for this ring object.

source(source)¶

Event – opcode 0 (attached to Proxy instance)

Ring event source

Source information for ring events.

This event does not occur on its own. It is sent before a wp_tablet_pad_ring.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 wp_tablet_pad_ring.source.finger, a wp_tablet_pad_ring.stop event will be sent when the user lifts the finger off the device.

This event is optional. If the source is unknown for an interaction, no event is sent.

Parameters:	source (ArgumentType.Uint) – the event source

angle(degrees)¶

Event – opcode 1 (attached to Proxy instance)

Angle changed

Sent whenever the angle on a ring changes.

The angle is provided in degrees clockwise from the logical north of the ring in the pad’s current rotation.

Parameters:	degrees (ArgumentType.Fixed) – the current angle in degrees

stop()¶

Event – opcode 2 (attached to Proxy instance)

Interaction stopped

Stop notification for ring events.

For some wp_tablet_pad_ring.source types, a wp_tablet_pad_ring.stop event is sent to notify a client that the interaction with the ring has terminated. This enables the client to implement kinetic scrolling. See the wp_tablet_pad_ring.source documentation for information on when this event may be generated.

Any wp_tablet_pad_ring.angle events with the same source after this event should be considered as the start of a new interaction.

frame(time)¶

Event – opcode 3 (attached to Proxy instance)

End of a ring event sequence

Indicates the end of a set of ring events that logically belong together. A client is expected to accumulate the data in all events within the frame before proceeding.

All wp_tablet_pad_ring events before a wp_tablet_pad_ring.frame event belong logically together. For example, on termination of a finger interaction on a ring the compositor will send a wp_tablet_pad_ring.source event, a wp_tablet_pad_ring.stop event and a wp_tablet_pad_ring.frame event.

A wp_tablet_pad_ring.frame event is sent for every logical event group, even if the group only contains a single wp_tablet_pad_ring event. Specifically, a client may get a sequence: angle, frame, angle, frame, etc.

Parameters:	time (ArgumentType.Uint) – timestamp with millisecond granularity

ZwpTabletManagerV2¶

class pywayland.protocol.tablet_unstable_v2.ZwpTabletManagerV2¶

Controller object for graphic tablet devices

An object that provides access to the graphics tablets available on this system. All tablets are associated with a seat, to get access to the actual tablets, use wp_tablet_manager.get_tablet_seat.

get_tablet_seat(seat)¶

Request – opcode 0 (attached to Resource instance)

Get the tablet seat

Get the wp_tablet_seat object for the given seat. This object provides access to all graphics tablets in this seat.

Parameters:	seat (`WlSeat`) – The `WlSeat` object to retrieve the tablets for
Returns:	`ZwpTabletSeatV2`

destroy()¶

Request – opcode 1 (attached to Resource instance)

Release the memory for the tablet manager object

Destroy the wp_tablet_manager object. Objects created from this object are unaffected and should be destroyed separately.

ZwpTabletPadStripV2¶

class pywayland.protocol.tablet_unstable_v2.ZwpTabletPadStripV2¶

Pad strip

A linear interaction area, such as the strips found in Wacom Cintiq models.

Events on a strip are logically grouped by the wl_tablet_pad_strip.frame event.

set_feedback(description, serial)¶

Request – opcode 0 (attached to Resource instance)

Set compositor feedback

Requests the compositor to use the provided feedback string associated with this strip. This request should be issued immediately after a wp_tablet_pad_group.mode_switch event from the corresponding group is received, or whenever the strip is mapped to a different action. See wp_tablet_pad_group.mode_switch for more details.

Clients are encouraged to provide context-aware descriptions for the actions associated with the strip, and compositors may use this information to offer visual feedback about the button layout (eg. on- screen displays).

The provided string ‘description’ is a UTF-8 encoded string to be associated with this ring, and is considered user-visible; general internationalization rules apply.

The serial argument will be that of the last wp_tablet_pad_group.mode_switch event received for the group of this strip. Requests providing other serials than the most recent one will be ignored.

Parameters:	description (ArgumentType.String) – strip description serial (ArgumentType.Uint) – serial of the mode switch event

destroy()¶

Request – opcode 1 (attached to Resource instance)

Destroy the strip object

This destroys the client’s resource for this strip object.

source(source)¶

Event – opcode 0 (attached to Proxy instance)

Strip event source

Source information for strip events.

This event does not occur on its own. It is sent before a wp_tablet_pad_strip.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 wp_tablet_pad_strip.source.finger, a wp_tablet_pad_strip.stop event will be sent when the user lifts their finger off the device.

This event is optional. If the source is unknown for an interaction, no event is sent.

Parameters:	source (ArgumentType.Uint) – the event source

position(position)¶

Event – opcode 1 (attached to Proxy instance)

Position changed

Sent whenever the position on a strip changes.

The position is normalized to a range of [0, 65535], the 0-value represents the top-most and/or left-most position of the strip in the pad’s current rotation.

Parameters:	position (ArgumentType.Uint) – the current position

stop()¶

Event – opcode 2 (attached to Proxy instance)

Interaction stopped

Stop notification for strip events.

For some wp_tablet_pad_strip.source types, a wp_tablet_pad_strip.stop event is sent to notify a client that the interaction with the strip has terminated. This enables the client to implement kinetic scrolling. See the wp_tablet_pad_strip.source documentation for information on when this event may be generated.

Any wp_tablet_pad_strip.position events with the same source after this event should be considered as the start of a new interaction.

frame(time)¶

Event – opcode 3 (attached to Proxy instance)

End of a strip event sequence

Indicates the end of a set of events that represent one logical hardware strip event. A client is expected to accumulate the data in all events within the frame before proceeding.

All wp_tablet_pad_strip events before a wp_tablet_pad_strip.frame event belong logically together. For example, on termination of a finger interaction on a strip the compositor will send a wp_tablet_pad_strip.source event, a wp_tablet_pad_strip.stop event and a wp_tablet_pad_strip.frame event.

A wp_tablet_pad_strip.frame event is sent for every logical event group, even if the group only contains a single wp_tablet_pad_strip event. Specifically, a client may get a sequence: position, frame, position, frame, etc.

Parameters:	time (ArgumentType.Uint) – timestamp with millisecond granularity

ZwpTabletPadV2¶

class pywayland.protocol.tablet_unstable_v2.ZwpTabletPadV2¶

A set of buttons, rings and strips

A pad device is a set of buttons, rings and strips usually physically present on the tablet device itself. Some exceptions exist where the pad device is physically detached, e.g. the Wacom ExpressKey Remote.

Pad devices have no axes that control the cursor and are generally auxiliary devices to the tool devices used on the tablet surface.

A pad device has a number of static characteristics, e.g. the number of rings. These capabilities are sent in an event sequence after the wp_tablet_seat.pad_added event before any actual events from this pad. This initial event sequence is terminated by a wp_tablet_pad.done event.

All pad features (buttons, rings and strips) are logically divided into groups and all pads have at least one group. The available groups are notified through the wp_tablet_pad.group event; the compositor will emit one event per group before emitting wp_tablet_pad.done.

Groups may have multiple modes. Modes allow clients to map multiple actions to a single pad feature. Only one mode can be active per group, although different groups may have different active modes.

set_feedback(button, description, serial)¶

Request – opcode 0 (attached to Resource instance)

Set compositor feedback

Requests the compositor to use the provided feedback string associated with this button. This request should be issued immediately after a wp_tablet_pad_group.mode_switch event from the corresponding group is received, or whenever a button is mapped to a different action. See wp_tablet_pad_group.mode_switch for more details.

Clients are encouraged to provide context-aware descriptions for the actions associated with each button, and compositors may use this information to offer visual feedback on the button layout (e.g. on- screen displays).

Button indices start at 0. Setting the feedback string on a button that is reserved by the compositor (i.e. not belonging to any wp_tablet_pad_group) does not generate an error but the compositor is free to ignore the request.

The provided string ‘description’ is a UTF-8 encoded string to be associated with this ring, and is considered user-visible; general internationalization rules apply.

The serial argument will be that of the last wp_tablet_pad_group.mode_switch event received for the group of this button. Requests providing other serials than the most recent one will be ignored.

Parameters:	button (ArgumentType.Uint) – button index description (ArgumentType.String) – button description serial (ArgumentType.Uint) – serial of the mode switch event

destroy()¶

Request – opcode 1 (attached to Resource instance)

Destroy the pad object

Destroy the wp_tablet_pad object. Objects created from this object are unaffected and should be destroyed separately.

group(pad_group)¶

Event – opcode 0 (attached to Proxy instance)

Group announced

Sent on wp_tablet_pad initialization to announce available groups. One event is sent for each pad group available.

This event is sent in the initial burst of events before the wp_tablet_pad.done event. At least one group will be announced.

Parameters:	pad_group (`ZwpTabletPadGroupV2`) –

path(path)¶

Event – opcode 1 (attached to Proxy instance)

Path to the device

A system-specific device path that indicates which device is behind this wp_tablet_pad. This information may be used to gather additional information about the device, e.g. through libwacom.

The format of the path is unspecified, it may be a device node, a sysfs path, or some other identifier. It is up to the client to identify the string provided.

This event is sent in the initial burst of events before the wp_tablet_pad.done event.

Parameters:	path (ArgumentType.String) – path to local device

buttons(buttons)¶

Event – opcode 2 (attached to Proxy instance)

Buttons announced

Sent on wp_tablet_pad initialization to announce the available buttons.

This event is sent in the initial burst of events before the wp_tablet_pad.done event. This event is only sent when at least one button is available.

Parameters:	buttons (ArgumentType.Uint) – the number of buttons

done()¶

Event – opcode 3 (attached to Proxy instance)

Pad description event sequence complete

This event signals the end of the initial burst of descriptive events. A client may consider the static description of the pad to be complete and finalize initialization of the pad.

button(time, button, state)¶

Event – opcode 4 (attached to Proxy instance)

Physical button state

Sent whenever the physical state of a button changes.

Parameters:	time (ArgumentType.Uint) – the time of the event with millisecond granularity button (ArgumentType.Uint) – the index of the button that changed state state (ArgumentType.Uint) –

enter(serial, tablet, surface)¶

Event – opcode 5 (attached to Proxy instance)

Enter event

Notification that this pad is focused on the specified surface.

Parameters:	serial (ArgumentType.Uint) – serial number of the enter event tablet (`ZwpTabletV2`) – the tablet the pad is attached to surface (`WlSurface`) – surface the pad is focused on

leave(serial, surface)¶

Event – opcode 6 (attached to Proxy instance)

Enter event

Notification that this pad is no longer focused on the specified surface.

Parameters:	serial (ArgumentType.Uint) – serial number of the leave event surface (`WlSurface`) – surface the pad is no longer focused on

removed()¶

Event – opcode 7 (attached to Proxy instance)

Pad removed event

Sent when the pad has been removed from the system. When a tablet is removed its pad(s) will be removed too.

When this event is received, the client must destroy all rings, strips and groups that were offered by this pad, and issue wp_tablet_pad.destroy the pad itself.

ZwpTabletToolV2¶

class pywayland.protocol.tablet_unstable_v2.ZwpTabletToolV2¶

A physical tablet tool

An object that represents a physical tool that has been, or is currently in use with a tablet in this seat. Each wp_tablet_tool object stays valid until the client destroys it; the compositor reuses the wp_tablet_tool object to indicate that the object’s respective physical tool has come into proximity of a tablet again.

A wp_tablet_tool object’s relation to a physical tool depends on the tablet’s ability to report serial numbers. If the tablet supports this capability, then the object represents a specific physical tool and can be identified even when used on multiple tablets.

A tablet tool has a number of static characteristics, e.g. tool type, hardware_serial and capabilities. These capabilities are sent in an event sequence after the wp_tablet_seat.tool_added event before any actual events from this tool. This initial event sequence is terminated by a wp_tablet_tool.done event.

Tablet tool events are grouped by wp_tablet_tool.frame events. Any events received before a wp_tablet_tool.frame event should be considered part of the same hardware state change.

set_cursor(serial, surface, hotspot_x, hotspot_y)¶

Request – opcode 0 (attached to Resource instance)

Set the tablet tool’s surface

Sets the surface of the cursor used for this tool on the given tablet. This request only takes effect if the tool is in proximity of 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 cursor image is hidden.

The parameters hotspot_x and hotspot_y define the position of the pointer surface relative to the pointer location. Its top-left corner is always at (x, y) - (hotspot_x, hotspot_y), where (x, y) are the coordinates of the pointer location, in surface-local coordinates.

On surface.attach requests to the pointer surface, hotspot_x and hotspot_y are decremented by the x and y parameters passed to the request. Attach must be confirmed by 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 current and pending input regions of the WlSurface are cleared, and WlSurface.set_input_region() is ignored until the WlSurface is no longer used as the cursor. When the use as a cursor ends, the current and pending input regions become undefined, and the WlSurface is unmapped.

This request gives the surface the role of a wp_tablet_tool cursor. A surface may only ever be used as the cursor surface for one wp_tablet_tool. If the surface already has another role or has previously been used as cursor surface for a different tool, a protocol error is raised.

Parameters:	serial (ArgumentType.Uint) – serial of the enter event surface (`WlSurface` or None) – hotspot_x (ArgumentType.Int) – surface-local x coordinate hotspot_y (ArgumentType.Int) – surface-local y coordinate

destroy()¶

Request – opcode 1 (attached to Resource instance)

Destroy the tool object

This destroys the client’s resource for this tool object.

type(tool_type)¶

Event – opcode 0 (attached to Proxy instance)

Tool type

The tool type is the high-level type of the tool and usually decides the interaction expected from this tool.

This event is sent in the initial burst of events before the wp_tablet_tool.done event.

Parameters:	tool_type (ArgumentType.Uint) – the physical tool type

hardware_serial(hardware_serial_hi, hardware_serial_lo)¶

Event – opcode 1 (attached to Proxy instance)

Unique hardware serial number of the tool

If the physical tool can be identified by a unique 64-bit serial number, this event notifies the client of this serial number.

If multiple tablets are available in the same seat and the tool is uniquely identifiable by the serial number, that tool may move between tablets.

Otherwise, if the tool has no serial number and this event is missing, the tool is tied to the tablet it first comes into proximity with. Even if the physical tool is used on multiple tablets, separate wp_tablet_tool objects will be created, one per tablet.

This event is sent in the initial burst of events before the wp_tablet_tool.done event.

Parameters:	hardware_serial_hi (ArgumentType.Uint) – the unique serial number of the tool, most significant bits hardware_serial_lo (ArgumentType.Uint) – the unique serial number of the tool, least significant bits

hardware_id_wacom(hardware_id_hi, hardware_id_lo)¶

Event – opcode 2 (attached to Proxy instance)

Hardware id notification in wacom’s format

This event notifies the client of a hardware id available on this tool.

The hardware id is a device-specific 64-bit id that provides extra information about the tool in use, beyond the wl_tool.type enumeration. The format of the id is specific to tablets made by Wacom Inc. For example, the hardware id of a Wacom Grip Pen (a stylus) is 0x802.

This event is sent in the initial burst of events before the wp_tablet_tool.done event.

Parameters:	hardware_id_hi (ArgumentType.Uint) – the hardware id, most significant bits hardware_id_lo (ArgumentType.Uint) – the hardware id, least significant bits

capability(capability)¶

Event – opcode 3 (attached to Proxy instance)

Tool capability notification

This event notifies the client of any capabilities of this tool, beyond the main set of x/y axes and tip up/down detection.

One event is sent for each extra capability available on this tool.

This event is sent in the initial burst of events before the wp_tablet_tool.done event.

Parameters:	capability (ArgumentType.Uint) – the capability

done()¶

Event – opcode 4 (attached to Proxy instance)

Tool description events sequence complete

This event signals the end of the initial burst of descriptive events. A client may consider the static description of the tool to be complete and finalize initialization of the tool.

removed()¶

Event – opcode 5 (attached to Proxy instance)

Tool removed

This event is sent when the tool is removed from the system and will send no further events. Should the physical tool come back into proximity later, a new wp_tablet_tool object will be created.

It is compositor-dependent when a tool is removed. A compositor may remove a tool on proximity out, tablet removal or any other reason. A compositor may also keep a tool alive until shutdown.

If the tool is currently in proximity, a proximity_out event will be sent before the removed event. See wp_tablet_tool.proximity_out for the handling of any buttons logically down.

When this event is received, the client must wp_tablet_tool.destroy the object.

proximity_in(serial, tablet, surface)¶

Event – opcode 6 (attached to Proxy instance)

Proximity in event

Notification that this tool is focused on a certain surface.

This event can be received when the tool has moved from one surface to another, or when the tool has come back into proximity above the surface.

If any button is logically down when the tool comes into proximity, the respective button event is sent after the proximity_in event but within the same frame as the proximity_in event.

Parameters:	serial (ArgumentType.Uint) – tablet (`ZwpTabletV2`) – The tablet the tool is in proximity of surface (`WlSurface`) – The current surface the tablet tool is over

proximity_out()¶

Event – opcode 7 (attached to Proxy instance)

Proximity out event

Notification that this tool has either left proximity, or is no longer focused on a certain surface.

When the tablet tool leaves proximity of the tablet, button release events are sent for each button that was held down at the time of leaving proximity. These events are sent before the proximity_out event but within the same wp_tablet.frame.

If the tool stays within proximity of the tablet, but the focus changes from one surface to another, a button release event may not be sent until the button is actually released or the tool leaves the proximity of the tablet.

down(serial)¶

Event – opcode 8 (attached to Proxy instance)

Tablet tool is making contact

Sent whenever the tablet tool comes in contact with the surface of the tablet.

If the tool is already in contact with the tablet when entering the input region, the client owning said region will receive a wp_tablet.proximity_in event, followed by a wp_tablet.down event and a wp_tablet.frame event.

Note that this event describes logical contact, not physical contact. On some devices, a compositor may not consider a tool in logical contact until a minimum physical pressure threshold is exceeded.

Parameters:	serial (ArgumentType.Uint) –

up()¶

Event – opcode 9 (attached to Proxy instance)

Tablet tool is no longer making contact

Sent whenever the tablet tool stops making contact with the surface of the tablet, or when the tablet tool moves out of the input region and the compositor grab (if any) is dismissed.

If the tablet tool moves out of the input region while in contact with the surface of the tablet and the compositor does not have an ongoing grab on the surface, the client owning said region will receive a wp_tablet.up event, followed by a wp_tablet.proximity_out event and a wp_tablet.frame event. If the compositor has an ongoing grab on this device, this event sequence is sent whenever the grab is dismissed in the future.

Note that this event describes logical contact, not physical contact. On some devices, a compositor may not consider a tool out of logical contact until physical pressure falls below a specific threshold.

motion(x, y)¶

Event – opcode 10 (attached to Proxy instance)

Motion event

Sent whenever a tablet tool moves.

Parameters:	x (ArgumentType.Fixed) – surface-local x coordinate y (ArgumentType.Fixed) – surface-local y coordinate

pressure(pressure)¶

Event – opcode 11 (attached to Proxy instance)

Pressure change event

Sent whenever the pressure axis on a tool changes. The value of this event is normalized to a value between 0 and 65535.

Note that pressure may be nonzero even when a tool is not in logical contact. See the down and up events for more details.

Parameters:	pressure (ArgumentType.Uint) – The current pressure value

distance(distance)¶

Event – opcode 12 (attached to Proxy instance)

Distance change event

Sent whenever the distance axis on a tool changes. The value of this event is normalized to a value between 0 and 65535.

Note that distance may be nonzero even when a tool is not in logical contact. See the down and up events for more details.

Parameters:	distance (ArgumentType.Uint) – The current distance value

tilt(tilt_x, tilt_y)¶

Event – opcode 13 (attached to Proxy instance)

Tilt change event

Sent whenever one or both of the tilt axes on a tool change. Each tilt value is in degrees, relative to the z-axis of the tablet. The angle is positive when the top of a tool tilts along the positive x or y axis.

Parameters:	tilt_x (ArgumentType.Fixed) – The current value of the X tilt axis tilt_y (ArgumentType.Fixed) – The current value of the Y tilt axis

rotation(degrees)¶

Event – opcode 14 (attached to Proxy instance)

Z-rotation change event

Sent whenever the z-rotation axis on the tool changes. The rotation value is in degrees clockwise from the tool’s logical neutral position.

Parameters:	degrees (ArgumentType.Fixed) – The current rotation of the Z axis

slider(position)¶

Event – opcode 15 (attached to Proxy instance)

Slider position change event

Sent whenever the slider position on the tool changes. The value is normalized between -65535 and 65535, with 0 as the logical neutral position of the slider.

The slider is available on e.g. the Wacom Airbrush tool.

Parameters:	position (ArgumentType.Int) – The current position of slider

wheel(degrees, clicks)¶

Event – opcode 16 (attached to Proxy instance)

Wheel delta event

Sent whenever the wheel on the tool emits an event. This event contains two values for the same axis change. The degrees value is in the same orientation as the WlPointer.vertical_scroll() axis. The clicks value is in discrete logical clicks of the mouse wheel. This value may be zero if the movement of the wheel was less than one logical click.

Clients should choose either value and avoid mixing degrees and clicks. The compositor may accumulate values smaller than a logical click and emulate click events when a certain threshold is met. Thus, wl_tablet_tool.wheel events with non-zero clicks values may have different degrees values.

Parameters:	degrees (ArgumentType.Fixed) – The wheel delta in degrees clicks (ArgumentType.Int) – The wheel delta in discrete clicks

button(serial, button, state)¶

Event – opcode 17 (attached to Proxy instance)

Button event

Sent whenever a button on the tool is pressed or released.

If a button is held down when the tool moves in or out of proximity, button events are generated by the compositor. See wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for details.

Parameters:	serial (ArgumentType.Uint) – button (ArgumentType.Uint) – The button whose state has changed state (ArgumentType.Uint) – Whether the button was pressed or released

frame(time)¶

Event – opcode 18 (attached to Proxy instance)

Frame event

Marks the end of a series of axis and/or button updates from the tablet. The Wayland protocol requires axis updates to be sent sequentially, however all events within a frame should be considered one hardware event.

Parameters:	time (ArgumentType.Uint) – The time of the event with millisecond granularity

ZwpTabletSeatV2¶

class pywayland.protocol.tablet_unstable_v2.ZwpTabletSeatV2¶

Controller object for graphic tablet devices of a seat

An object that provides access to the graphics tablets available on this seat. After binding to this interface, the compositor sends a set of wp_tablet_seat.tablet_added and wp_tablet_seat.tool_added events.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Release the memory for the tablet seat object

Destroy the wp_tablet_seat object. Objects created from this object are unaffected and should be destroyed separately.

tablet_added(id)¶

Event – opcode 0 (attached to Proxy instance)

New device notification

This event is sent whenever a new tablet becomes available on this seat. This event only provides the object id of the tablet, any static information about the tablet (device name, vid/pid, etc.) is sent through the wp_tablet interface.

Parameters:	id (`ZwpTabletV2`) – the newly added graphics tablet

tool_added(id)¶

Event – opcode 1 (attached to Proxy instance)

A new tool has been used with a tablet

This event is sent whenever a tool that has not previously been used with a tablet comes into use. This event only provides the object id of the tool; any static information about the tool (capabilities, type, etc.) is sent through the wp_tablet_tool interface.

Parameters:	id (`ZwpTabletToolV2`) – the newly added tablet tool

pad_added(id)¶

Event – opcode 2 (attached to Proxy instance)

New pad notification

This event is sent whenever a new pad is known to the system. Typically, pads are physically attached to tablets and a pad_added event is sent immediately after the wp_tablet_seat.tablet_added. However, some standalone pad devices logically attach to tablets at runtime, and the client must wait for wp_tablet_pad.enter to know the tablet a pad is attached to.

This event only provides the object id of the pad. All further features (buttons, strips, rings) are sent through the wp_tablet_pad interface.

Parameters:	id (`ZwpTabletPadV2`) – the newly added pad

ZwpTabletV2¶

class pywayland.protocol.tablet_unstable_v2.ZwpTabletV2¶

Graphics tablet device

The wp_tablet interface represents one graphics tablet device. The tablet interface itself does not generate events; all events are generated by wp_tablet_tool objects when in proximity above a tablet.

A tablet has a number of static characteristics, e.g. device name and pid/vid. These capabilities are sent in an event sequence after the wp_tablet_seat.tablet_added event. This initial event sequence is terminated by a wp_tablet.done event.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the tablet object

This destroys the client’s resource for this tablet object.

name(name)¶

Event – opcode 0 (attached to Proxy instance)

Tablet device name

This event is sent in the initial burst of events before the wp_tablet.done event.

Parameters:	name (ArgumentType.String) – the device name

id(vid, pid)¶

Event – opcode 1 (attached to Proxy instance)

Tablet device usb vendor/product id

This event is sent in the initial burst of events before the wp_tablet.done event.

Parameters:	vid (ArgumentType.Uint) – USB vendor id pid (ArgumentType.Uint) – USB product id

path(path)¶

Event – opcode 2 (attached to Proxy instance)

Path to the device

A system-specific device path that indicates which device is behind this wp_tablet. This information may be used to gather additional information about the device, e.g. through libwacom.

A device may have more than one device path. If so, multiple wp_tablet.path events are sent. A device may be emulated and not have a device path, and in that case this event will not be sent.

The format of the path is unspecified, it may be a device node, a sysfs path, or some other identifier. It is up to the client to identify the string provided.

This event is sent in the initial burst of events before the wp_tablet.done event.

Parameters:	path (ArgumentType.String) – path to local device

done()¶

Event – opcode 3 (attached to Proxy instance)

Tablet description events sequence complete

This event is sent immediately to signal the end of the initial burst of descriptive events. A client may consider the static description of the tablet to be complete and finalize initialization of the tablet.

removed()¶

Event – opcode 4 (attached to Proxy instance)

Tablet removed event

Sent when the tablet has been removed from the system. When a tablet is removed, some tools may be removed.

When this event is received, the client must wp_tablet.destroy the object.

ZwpTabletPadGroupV2¶

class pywayland.protocol.tablet_unstable_v2.ZwpTabletPadGroupV2¶

A set of buttons, rings and strips

A pad group describes a distinct (sub)set of buttons, rings and strips present in the tablet. The criteria of this grouping is usually positional, eg. if a tablet has buttons on the left and right side, 2 groups will be presented. The physical arrangement of groups is undisclosed and may change on the fly.

Pad groups will announce their features during pad initialization. Between the corresponding wp_tablet_pad.group event and wp_tablet_pad_group.done, the pad group will announce the buttons, rings and strips contained in it, plus the number of supported modes.

Modes are a mechanism to allow multiple groups of actions for every element in the pad group. The number of groups and available modes in each is persistent across device plugs. The current mode is user-switchable, it will be announced through the wp_tablet_pad_group.mode_switch event both whenever it is switched, and after wp_tablet_pad.enter.

The current mode logically applies to all elements in the pad group, although it is at clients’ discretion whether to actually perform different actions, and/or issue the respective .set_feedback requests to notify the compositor. See the wp_tablet_pad_group.mode_switch event for more details.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the pad object

Destroy the wp_tablet_pad_group object. Objects created from this object are unaffected and should be destroyed separately.

buttons(buttons)¶

Event – opcode 0 (attached to Proxy instance)

Buttons announced

Sent on wp_tablet_pad_group initialization to announce the available buttons in the group. Button indices start at 0, a button may only be in one group at a time.

This event is first sent in the initial burst of events before the wp_tablet_pad_group.done event.

Some buttons are reserved by the compositor. These buttons may not be assigned to any wp_tablet_pad_group. Compositors may broadcast this event in the case of changes to the mapping of these reserved buttons. If the compositor happens to reserve all buttons in a group, this event will be sent with an empty array.

Parameters:	buttons (ArgumentType.Array) – buttons in this group

ring(ring)¶

Event – opcode 1 (attached to Proxy instance)

Ring announced

Sent on wp_tablet_pad_group initialization to announce available rings. One event is sent for each ring available on this pad group.

This event is sent in the initial burst of events before the wp_tablet_pad_group.done event.

Parameters:	ring (`ZwpTabletPadRingV2`) –

strip(strip)¶

Event – opcode 2 (attached to Proxy instance)

Strip announced

Sent on wp_tablet_pad initialization to announce available strips. One event is sent for each strip available on this pad group.

This event is sent in the initial burst of events before the wp_tablet_pad_group.done event.

Parameters:	strip (`ZwpTabletPadStripV2`) –

modes(modes)¶

Event – opcode 3 (attached to Proxy instance)

Mode-switch ability announced

Sent on wp_tablet_pad_group initialization to announce that the pad group may switch between modes. A client may use a mode to store a specific configuration for buttons, rings and strips and use the wl_tablet_pad_group.mode_switch event to toggle between these configurations. Mode indices start at 0.

Switching modes is compositor-dependent. See the wp_tablet_pad_group.mode_switch event for more details.

This event is sent in the initial burst of events before the wp_tablet_pad_group.done event. This event is only sent when more than more than one mode is available.

Parameters:	modes (ArgumentType.Uint) – the number of modes

done()¶

Event – opcode 4 (attached to Proxy instance)

Tablet group description events sequence complete

This event is sent immediately to signal the end of the initial burst of descriptive events. A client may consider the static description of the tablet to be complete and finalize initialization of the tablet group.

mode_switch(time, serial, mode)¶

Event – opcode 5 (attached to Proxy instance)

Mode switch event

Notification that the mode was switched.

A mode applies to all buttons, rings and strips in a group simultaneously, but a client is not required to assign different actions for each mode. For example, a client may have mode-specific button mappings but map the ring to vertical scrolling in all modes. Mode indices start at 0.

Switching modes is compositor-dependent. The compositor may provide visual cues to the client about the mode, e.g. by toggling LEDs on the tablet device. Mode-switching may be software-controlled or controlled by one or more physical buttons. For example, on a Wacom Intuos Pro, the button inside the ring may be assigned to switch between modes.

The compositor will also send this event after wp_tablet_pad.enter on each group in order to notify of the current mode. Groups that only feature one mode will use mode=0 when emitting this event.

If a button action in the new mode differs from the action in the previous mode, the client should immediately issue a wp_tablet_pad.set_feedback request for each changed button.

If a ring or strip action in the new mode differs from the action in the previous mode, the client should immediately issue a wp_tablet_ring.set_feedback or wp_tablet_strip.set_feedback request for each changed ring or strip.

Parameters:	time (ArgumentType.Uint) – the time of the event with millisecond granularity serial (ArgumentType.Uint) – mode (ArgumentType.Uint) – the new mode of the pad

text_input_unstable_v1 Module¶

ZwpTextInputManagerV1¶

class pywayland.protocol.text_input_unstable_v1.ZwpTextInputManagerV1¶

Text input manager

A factory for text_input objects. This object is a global singleton.

create_text_input()¶

Request – opcode 0 (attached to Resource instance)

Create text input

Creates a new text_input object.

Returns:	`ZwpTextInputV1`

ZwpTextInputV1¶

class pywayland.protocol.text_input_unstable_v1.ZwpTextInputV1¶

Text input

An object used for text input. Adds support for text input and input methods to applications. A text_input object is created from a wl_text_input_manager and corresponds typically to a text entry in an application.

Requests are used to activate/deactivate the text_input object and set state information like surrounding and selected text or the content type. The information about entered text is sent to the text_input object via the pre-edit and commit events. Using this interface removes the need for applications to directly process hardware key events and compose text out of them.

Text is generally UTF-8 encoded, indices and lengths are in bytes.

Serials are used to synchronize the state between the text input and an input method. New serials are sent by the text input in the commit_state request and are used by the input method to indicate the known text input state in events like preedit_string, commit_string, and keysym. The text input can then ignore events from the input method which are based on an outdated state (for example after a reset).

Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.

activate(seat, surface)¶

Request – opcode 0 (attached to Resource instance)

Request activation

Requests the text_input object to be activated (typically when the text entry gets focus).

The seat argument is a WlSeat which maintains the focus for this activation. The surface argument is a WlSurface assigned to the text_input object and tracked for focus lost. The enter event is emitted on successful activation.

Parameters:	seat (`WlSeat`) – surface (`WlSurface`) –

deactivate(seat)¶

Request – opcode 1 (attached to Resource instance)

Request deactivation

Requests the text_input object to be deactivated (typically when the text entry lost focus). The seat argument is a WlSeat which was used for activation.

Parameters:	seat (`WlSeat`) –

show_input_panel()¶

Request – opcode 2 (attached to Resource instance)

Show input panels

Requests input panels (virtual keyboard) to show.

hide_input_panel()¶

Request – opcode 3 (attached to Resource instance)

Hide input panels

Requests input panels (virtual keyboard) to hide.

reset()¶

Request – opcode 4 (attached to Resource instance)

Reset

Should be called by an editor widget when the input state should be reset, for example after the text was changed outside of the normal input method flow.

set_surrounding_text(text, cursor, anchor)¶

Request – opcode 5 (attached to Resource instance)

Sets the surrounding text

Sets the plain surrounding text around the input position. Text is UTF-8 encoded. Cursor is the byte offset within the surrounding text. Anchor is the byte offset of the selection anchor within the surrounding text. If there is no selected text anchor, then it is the same as cursor.

Parameters:	text (ArgumentType.String) – cursor (ArgumentType.Uint) – anchor (ArgumentType.Uint) –

set_content_type(hint, purpose)¶

Request – opcode 6 (attached to Resource instance)

Set content purpose and hint

Sets the content purpose and content hint. While the purpose is the basic purpose of an input field, the hint flags allow to modify some of the behavior.

When no content type is explicitly set, a normal content purpose with default hints (auto completion, auto correction, auto capitalization) should be assumed.

Parameters:	hint (ArgumentType.Uint) – purpose (ArgumentType.Uint) –

set_cursor_rectangle(x, y, width, height)¶

Request – opcode 7 (attached to Resource instance)

set_cursor_rectangle

Parameters:	x (ArgumentType.Int) – y (ArgumentType.Int) – width (ArgumentType.Int) – height (ArgumentType.Int) –

set_preferred_language(language)¶

Request – opcode 8 (attached to Resource instance)

Sets preferred language

Sets a specific language. This allows for example a virtual keyboard to show a language specific layout. The “language” argument is an RFC-3066 format language tag.

It could be used for example in a word processor to indicate the language of the currently edited document or in an instant message application which tracks languages of contacts.

Parameters:	language (ArgumentType.String) –

commit_state(serial)¶

Request – opcode 9 (attached to Resource instance)

commit_state

Parameters:	serial (ArgumentType.Uint) – used to identify the known state

invoke_action(button, index)¶

Request – opcode 10 (attached to Resource instance)

invoke_action

Parameters:	button (ArgumentType.Uint) – index (ArgumentType.Uint) –

enter(surface)¶

Event – opcode 0 (attached to Proxy instance)

Enter event

Notify the text_input object when it received focus. Typically in response to an activate request.

Parameters:	surface (`WlSurface`) –

leave()¶

Event – opcode 1 (attached to Proxy instance)

Leave event

Notify the text_input object when it lost focus. Either in response to a deactivate request or when the assigned surface lost focus or was destroyed.

modifiers_map(map)¶

Event – opcode 2 (attached to Proxy instance)

Modifiers map

Transfer an array of 0-terminated modifier names. The position in the array is the index of the modifier as used in the modifiers bitmask in the keysym event.

Parameters:	map (ArgumentType.Array) –

input_panel_state(state)¶

Event – opcode 3 (attached to Proxy instance)

State of the input panel

Notify when the visibility state of the input panel changed.

Parameters:	state (ArgumentType.Uint) –

preedit_string(serial, text, commit)¶

Event – opcode 4 (attached to Proxy instance)

Pre-edit

Notify when a new composing text (pre-edit) should be set around the current cursor position. Any previously set composing text should be removed.

The commit text can be used to replace the preedit text on reset (for example on unfocus).

The text input should also handle all preedit_style and preedit_cursor events occurring directly before preedit_string.

Parameters:	serial (ArgumentType.Uint) – serial of the latest known text input state text (ArgumentType.String) – commit (ArgumentType.String) –

preedit_styling(index, length, style)¶

Event – opcode 5 (attached to Proxy instance)

Pre-edit styling

Sets styling information on composing text. The style is applied for length bytes from index relative to the beginning of the composing text (as byte offset). Multiple styles can be applied to a composing text by sending multiple preedit_styling events.

This event is handled as part of a following preedit_string event.

Parameters:	index (ArgumentType.Uint) – length (ArgumentType.Uint) – style (ArgumentType.Uint) –

preedit_cursor(index)¶

Event – opcode 6 (attached to Proxy instance)

Pre-edit cursor

Sets the cursor position inside the composing text (as byte offset) relative to the start of the composing text. When index is a negative number no cursor is shown.

This event is handled as part of a following preedit_string event.

Parameters:	index (ArgumentType.Int) –

commit_string(serial, text)¶

Event – opcode 7 (attached to Proxy instance)

Commit

Notify when text should be inserted into the editor widget. The text to commit could be either just a single character after a key press or the result of some composing (pre-edit). It could also be an empty text when some text should be removed (see delete_surrounding_text) or when the input cursor should be moved (see cursor_position).

Any previously set composing text should be removed.

Parameters:	serial (ArgumentType.Uint) – serial of the latest known text input state text (ArgumentType.String) –

cursor_position(index, anchor)¶

Event – opcode 8 (attached to Proxy instance)

Set cursor to new position

Notify when the cursor or anchor position should be modified.

This event should be handled as part of a following commit_string event.

Parameters:	index (ArgumentType.Int) – anchor (ArgumentType.Int) –

delete_surrounding_text(index, length)¶

Event – opcode 9 (attached to Proxy instance)

Delete surrounding text

Notify when the text around the current cursor position should be deleted.

Index is relative to the current cursor (in bytes). Length is the length of deleted text (in bytes).

This event should be handled as part of a following commit_string event.

Parameters:	index (ArgumentType.Int) – length (ArgumentType.Uint) –

keysym(serial, time, sym, state, modifiers)¶

Event – opcode 10 (attached to Proxy instance)

Keysym

Notify when a key event was sent. Key events should not be used for normal text input operations, which should be done with commit_string, delete_surrounding_text, etc. The key event follows the WlKeyboard key event convention. Sym is an XKB keysym, state a WlKeyboard key_state. Modifiers are a mask for effective modifiers (where the modifier indices are set by the modifiers_map event)

Parameters:	serial (ArgumentType.Uint) – serial of the latest known text input state time (ArgumentType.Uint) – sym (ArgumentType.Uint) – state (ArgumentType.Uint) – modifiers (ArgumentType.Uint) –

language(serial, language)¶

Event – opcode 11 (attached to Proxy instance)

Language

Sets the language of the input text. The “language” argument is an RFC-3066 format language tag.

Parameters:	serial (ArgumentType.Uint) – serial of the latest known text input state language (ArgumentType.String) –

text_direction(serial, direction)¶

Event – opcode 12 (attached to Proxy instance)

Text direction

Sets the text direction of input text.

It is mainly needed for showing an input cursor on the correct side of the editor when there is no input done yet and making sure neutral direction text is laid out properly.

Parameters:	serial (ArgumentType.Uint) – serial of the latest known text input state direction (ArgumentType.Uint) –

text_input_unstable_v3 Module¶

ZwpTextInputManagerV3¶

class pywayland.protocol.text_input_unstable_v3.ZwpTextInputManagerV3¶

Text input manager

A factory for text-input objects. This object is a global singleton.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the wp_text_input_manager

Destroy the wp_text_input_manager object.

get_text_input(seat)¶

Request – opcode 1 (attached to Resource instance)

Create a new text input object

Creates a new text-input object for a given seat.

Parameters:	seat (`WlSeat`) –
Returns:	`ZwpTextInputV3`

ZwpTextInputV3¶

class pywayland.protocol.text_input_unstable_v3.ZwpTextInputV3¶

Text input

The ZwpTextInputV3 interface represents text input and input methods associated with a seat. It provides enter/leave events to follow the text input focus for a seat.

Requests are used to enable/disable the text-input object and set state information like surrounding and selected text or the content type. The information about the entered text is sent to the text-input object via the preedit_string and commit_string events.

Text is valid UTF-8 encoded, indices and lengths are in bytes. Indices must not point to middle bytes inside a code point: they must either point to the first byte of a code point or to the end of the buffer. Lengths must be measured between two valid indices.

Focus moving throughout surfaces will result in the emission of ZwpTextInputV3.enter() and ZwpTextInputV3.leave() events. The focused surface must commit ZwpTextInputV3.enable() and ZwpTextInputV3.disable() requests as the keyboard focus moves across editable and non-editable elements of the UI. Those two requests are not expected to be paired with each other, the compositor must be able to handle consecutive series of the same request.

State is sent by the state requests (set_surrounding_text, set_content_type and set_cursor_rectangle) and a commit request. After an enter event or disable request all state information is invalidated and needs to be resent by the client.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the wp_text_input

Destroy the wp_text_input object. Also disables all surfaces enabled through this wp_text_input object.

enable()¶

Request – opcode 1 (attached to Resource instance)

Request text input to be enabled

Requests text input on the surface previously obtained from the enter event.

This request must be issued every time the active text input changes to a new one, including within the current surface. Use ZwpTextInputV3.disable() when there is no longer any input focus on the current surface.

This request resets all state associated with previous enable, disable, set_surrounding_text, set_text_change_cause, set_content_type, and set_cursor_rectangle requests, as well as the state associated with preedit_string, commit_string, and delete_surrounding_text events.

The set_surrounding_text, set_content_type and set_cursor_rectangle requests must follow if the text input supports the necessary functionality.

State set with this request is double-buffered. It will get applied on the next ZwpTextInputV3.commit() request, and stay valid until the next committed enable or disable request.

The changes must be applied by the compositor after issuing a ZwpTextInputV3.commit() request.

disable()¶

Request – opcode 2 (attached to Resource instance)

Disable text input on a surface

Explicitly disable text input on the current surface (typically when there is no focus on any text entry inside the surface).

State set with this request is double-buffered. It will get applied on the next ZwpTextInputV3.commit() request.

set_surrounding_text(text, cursor, anchor)¶

Request – opcode 3 (attached to Resource instance)

Sets the surrounding text

Sets the surrounding plain text around the input, excluding the preedit text.

The client should notify the compositor of any changes in any of the values carried with this request, including changes caused by handling incoming text-input events as well as changes caused by other mechanisms like keyboard typing.

If the client is unaware of the text around the cursor, it should not issue this request, to signify lack of support to the compositor.

Text is UTF-8 encoded, and should include the cursor position, the complete selection and additional characters before and after them. There is a maximum length of wayland messages, so text can not be longer than 4000 bytes.

Cursor is the byte offset of the cursor within text buffer.

Anchor is the byte offset of the selection anchor within text buffer. If there is no selected text, anchor is the same as cursor.

If any preedit text is present, it is replaced with a cursor for the purpose of this event.

Values set with this request are double-buffered. They will get applied on the next ZwpTextInputV3.commit() request, and stay valid until the next committed enable or disable request.

The initial state for affected fields is empty, meaning that the text input does not support sending surrounding text. If the empty values get applied, subsequent attempts to change them may have no effect.

Parameters:	text (ArgumentType.String) – cursor (ArgumentType.Int) – anchor (ArgumentType.Int) –

set_text_change_cause(cause)¶

Request – opcode 4 (attached to Resource instance)

Indicates the cause of surrounding text change

Tells the compositor why the text surrounding the cursor changed.

Whenever the client detects an external change in text, cursor, or anchor posision, it must issue this request to the compositor. This request is intended to give the input method a chance to update the preedit text in an appropriate way, e.g. by removing it when the user starts typing with a keyboard.

cause describes the source of the change.

The value set with this request is double-buffered. It must be applied and reset to initial at the next ZwpTextInputV3.commit() request.

The initial value of cause is input_method.

Parameters:	cause (ArgumentType.Uint) –

set_content_type(hint, purpose)¶

Request – opcode 5 (attached to Resource instance)

Set content purpose and hint

Sets the content purpose and content hint. While the purpose is the basic purpose of an input field, the hint flags allow to modify some of the behavior.

Values set with this request are double-buffered. They will get applied on the next ZwpTextInputV3.commit() request. Subsequent attempts to update them may have no effect. The values remain valid until the next committed enable or disable request.

The initial value for hint is none, and the initial value for purpose is normal.

Parameters:	hint (ArgumentType.Uint) – purpose (ArgumentType.Uint) –

set_cursor_rectangle(x, y, width, height)¶

Request – opcode 6 (attached to Resource instance)

Set cursor position

Marks an area around the cursor as a x, y, width, height rectangle in surface local coordinates.

Allows the compositor to put a window with word suggestions near the cursor, without obstructing the text being input.

If the client is unaware of the position of edited text, it should not issue this request, to signify lack of support to the compositor.

Values set with this request are double-buffered. They will get applied on the next ZwpTextInputV3.commit() request, and stay valid until the next committed enable or disable request.

The initial values describing a cursor rectangle are empty. That means the text input does not support describing the cursor area. If the empty values get applied, subsequent attempts to change them may have no effect.

Parameters:	x (ArgumentType.Int) – y (ArgumentType.Int) – width (ArgumentType.Int) – height (ArgumentType.Int) –

commit()¶

Request – opcode 7 (attached to Resource instance)

Commit state

Atomically applies state changes recently sent to the compositor.

The commit request establishes and updates the state of the client, and must be issued after any changes to apply them.

Text input state (enabled status, content purpose, content hint, surrounding text and change cause, cursor rectangle) is conceptually double-buffered within the context of a text input, i.e. between a committed enable request and the following committed enable or disable request.

Protocol requests modify the pending state, as opposed to the current state in use by the input method. A commit request atomically applies all pending state, replacing the current state. After commit, the new pending state is as documented for each related request.

Requests are applied in the order of arrival.

Neither current nor pending state are modified unless noted otherwise.

The compositor must count the number of commit requests coming from each ZwpTextInputV3 object and use the count as the serial in done events.

enter(surface)¶

Event – opcode 0 (attached to Proxy instance)

Enter event

Notification that this seat’s text-input focus is on a certain surface.

When the seat has the keyboard capability the text-input focus follows the keyboard focus. This event sets the current surface for the text- input object.

Parameters:	surface (`WlSurface`) –

leave(surface)¶

Event – opcode 1 (attached to Proxy instance)

Leave event

Notification that this seat’s text-input focus is no longer on a certain surface. The client should reset any preedit string previously set.

The leave notification clears the current surface. It is sent before the enter notification for the new focus.

When the seat has the keyboard capability the text-input focus follows the keyboard focus.

Parameters:	surface (`WlSurface`) –

preedit_string(text, cursor_begin, cursor_end)¶

Event – opcode 2 (attached to Proxy instance)

Pre-edit

Notify when a new composing text (pre-edit) should be set at the current cursor position. Any previously set composing text must be removed. Any previously existing selected text must be removed.

The argument text contains the pre-edit string buffer.

The parameters cursor_begin and cursor_end are counted in bytes relative to the beginning of the submitted text buffer. Cursor should be hidden when both are equal to -1.

They could be represented by the client as a line if both values are the same, or as a text highlight otherwise.

Values set with this event are double-buffered. They must be applied and reset to initial on the next ZwpTextInputV3.done() event.

The initial value of text is an empty string, and cursor_begin, cursor_end and cursor_hidden are all 0.

Parameters:	text (ArgumentType.String or None) – cursor_begin (ArgumentType.Int) – cursor_end (ArgumentType.Int) –

commit_string(text)¶

Event – opcode 3 (attached to Proxy instance)

Text commit

Notify when text should be inserted into the editor widget. The text to commit could be either just a single character after a key press or the result of some composing (pre-edit).

Values set with this event are double-buffered. They must be applied and reset to initial on the next ZwpTextInputV3.done() event.

The initial value of text is an empty string.

Parameters:	text (ArgumentType.String or None) –

delete_surrounding_text(before_length, after_length)¶

Event – opcode 4 (attached to Proxy instance)

Delete surrounding text

Notify when the text around the current cursor position should be deleted.

Before_length and after_length are the number of bytes before and after the current cursor index (excluding the selection) to delete.

If a preedit text is present, in effect before_length is counted from the beginning of it, and after_length from its end (see done event sequence).

Values set with this event are double-buffered. They must be applied and reset to initial on the next ZwpTextInputV3.done() event.

The initial values of both before_length and after_length are 0.

Parameters:	before_length (ArgumentType.Uint) – length of text before current cursor position after_length (ArgumentType.Uint) – length of text after current cursor position

done(serial)¶

Event – opcode 5 (attached to Proxy instance)

Apply changes

Instruct the application to apply changes to state requested by the preedit_string, commit_string and delete_surrounding_text events. The state relating to these events is double-buffered, and each one modifies the pending state. This event replaces the current state with the pending state.

The application must proceed by evaluating the changes in the following order:

1. Replace existing preedit string with the cursor. 2. Delete requested surrounding text. 3. Insert commit string with the cursor at its end. 4. Calculate surrounding text to send. 5. Insert new preedit text in cursor position. 6. Place cursor inside preedit text.

The serial number reflects the last state of the ZwpTextInputV3 object known to the compositor. The value of the serial argument must be equal to the number of commit requests already issued on that object. When the client receives a done event with a serial different than the number of past commit requests, it must proceed as normal, except it should not change the current state of the ZwpTextInputV3 object.

Parameters:	serial (ArgumentType.Uint) –

viewporter Module¶

WpViewport¶

class pywayland.protocol.viewporter.WpViewport¶

Crop and scale interface to a WlSurface

An additional interface to a WlSurface object, which allows the client to specify the cropping and scaling of the surface contents.

This interface works with two concepts: the source rectangle (src_x, src_y, src_width, src_height), and the destination size (dst_width, dst_height). The contents of the source rectangle are scaled to the destination size, and content outside the source rectangle is ignored. This state is double- buffered, and is applied on the next WlSurface.commit().

The two parts of crop and scale state are independent: the source rectangle, and the destination size. Initially both are unset, that is, no scaling is applied. The whole of the current WlBuffer is used as the source, and the surface size is as defined in WlSurface.attach().

If the destination size is set, it causes the surface size to become dst_width, dst_height. The source (rectangle) is scaled to exactly this size. This overrides whatever the attached WlBuffer size is, unless the WlBuffer is NULL. If the WlBuffer is NULL, the surface has no content and therefore no size. Otherwise, the size is always at least 1x1 in surface local coordinates.

If the source rectangle is set, it defines what area of the WlBuffer is taken as the source. If the source rectangle is set and the destination size is not set, then src_width and src_height must be integers, and the surface size becomes the source rectangle size. This results in cropping without scaling. If src_width or src_height are not integers and destination size is not set, the bad_size protocol error is raised when the surface state is applied.

The coordinate transformations from buffer pixel coordinates up to the surface-local coordinates happen in the following order: 1. buffer_transform (WlSurface.set_buffer_transform()) 2. buffer_scale (WlSurface.set_buffer_scale()) 3. crop and scale (WpViewport.set*) This means, that the source rectangle coordinates of crop and scale are given in the coordinates after the buffer transform and scale, i.e. in the coordinates that would be the surface- local coordinates if the crop and scale was not applied.

If src_x or src_y are negative, the bad_value protocol error is raised. Otherwise, if the source rectangle is partially or completely outside of the non-NULL WlBuffer, then the out_of_buffer protocol error is raised when the surface state is applied. A NULL WlBuffer does not raise the out_of_buffer error.

The x, y arguments of WlSurface.attach() are applied as normal to the surface. They indicate how many pixels to remove from the surface size from the left and the top. In other words, they are still in the surface-local coordinate system, just like dst_width and dst_height are.

If the WlSurface associated with the WpViewport is destroyed, all WpViewport requests except ‘destroy’ raise the protocol error no_surface.

If the WpViewport object is destroyed, the crop and scale state is removed from the WlSurface. The change will be applied on the next WlSurface.commit().

destroy()¶

Request – opcode 0 (attached to Resource instance)

Remove scaling and cropping from the surface

The associated wl_surface’s crop and scale state is removed. The change is applied on the next WlSurface.commit().

set_source(x, y, width, height)¶

Request – opcode 1 (attached to Resource instance)

Set the source rectangle for cropping

Set the source rectangle of the associated WlSurface. See WpViewport for the description, and relation to the WlBuffer size.

If all of x, y, width and height are -1.0, the source rectangle is unset instead. Any other set of values where width or height are zero or negative, or x or y are negative, raise the bad_value protocol error.

The crop and scale state is double-buffered state, and will be applied on the next WlSurface.commit().

Parameters:	x (ArgumentType.Fixed) – source rectangle x y (ArgumentType.Fixed) – source rectangle y width (ArgumentType.Fixed) – source rectangle width height (ArgumentType.Fixed) – source rectangle height

set_destination(width, height)¶

Request – opcode 2 (attached to Resource instance)

Set the surface size for scaling

Set the destination size of the associated WlSurface. See WpViewport for the description, and relation to the WlBuffer size.

If width is -1 and height is -1, the destination size is unset instead. Any other pair of values for width and height that contains zero or negative values raises the bad_value protocol error.

The crop and scale state is double-buffered state, and will be applied on the next WlSurface.commit().

Parameters:	width (ArgumentType.Int) – surface width height (ArgumentType.Int) – surface height

WpViewporter¶

class pywayland.protocol.viewporter.WpViewporter¶

Surface cropping and scaling

The global interface exposing surface cropping and scaling capabilities is used to instantiate an interface extension for a WlSurface object. This extended interface will then allow cropping and scaling the surface contents, effectively disconnecting the direct relationship between the buffer and the surface size.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Unbind from the cropping and scaling interface

Informs the server that the client will not be using this protocol object anymore. This does not affect any other objects, WpViewport objects included.

get_viewport(surface)¶

Request – opcode 1 (attached to Resource instance)

Extend surface interface for crop and scale

Instantiate an interface extension for the given WlSurface to crop and scale its content. If the given WlSurface already has a WpViewport object associated, the viewport_exists protocol error is raised.

Parameters:	surface (`WlSurface`) – the surface
Returns:	`WpViewport` – the new viewport interface id

wayland Module¶

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, origin, icon, serial)¶

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.

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.attach() request 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 current and pending input regions of the icon WlSurface are cleared, and WlSurface.set_input_region() is ignored until the WlSurface is no longer used as the icon surface. When the use as an icon ends, the current and pending input regions become undefined, and the WlSurface is unmapped.

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, serial)¶

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.

Parameters:	source (`WlDataSource` or None) – data source for the selection serial (ArgumentType.Uint) – serial number of the event that triggered this request

release()¶

Request – opcode 2 (attached to Resource instance)

Destroy data device

This request destroys the data device.

data_offer(id)¶

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, surface, x, y, id)¶

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()¶

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, x, y)¶

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()¶

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)¶

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. The client must destroy the previous selection data_offer, if any, upon receiving this event.

Parameters:	id (`WlDataOffer` or None) – selection data_offer object

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()¶

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, parent)¶

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 a 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.

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

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()¶

Request – opcode 0 (attached to Resource instance)

Release the touch object

down(serial, time, surface, id, x, y)¶

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, time, id)¶

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, id, x, y)¶

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()¶

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()¶

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.

shape(id, major, minor)¶

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, orientation)¶

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

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)¶

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()¶

Request – opcode 1 (attached to Resource instance)

Destroy the data source

Destroy the data source.

set_actions(dnd_actions)¶

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)¶

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, fd)¶

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()¶

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()¶

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()¶

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)¶

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

WlCallback¶

class pywayland.protocol.wayland.WlCallback¶

Callback object

Clients can handle the ‘done’ event to get notified when the related request is done.

done(callback_data)¶

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

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()¶

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)¶

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

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 wl_drm, WlShm 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.

destroy()¶

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()¶

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.

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.

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()¶

Request – opcode 0 (attached to Resource instance)

Delete surface

Deletes the surface and invalidates its object ID.

attach(buffer, x, y)¶

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 the supplied buffer must be an integer multiple of the buffer_scale.

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 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. However, if the client destroys the WlBuffer before receiving the WlBuffer.release() event, the surface contents become undefined immediately.

If WlSurface.attach() is sent with a NULL WlBuffer, the following WlSurface.commit() will remove the surface content.

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, y, width, height)¶

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()¶

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)¶

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)¶

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()¶

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 current state in use by the compositor. A commit request atomically applies all pending state, replacing the current state. After commit, the new pending state is as documented for each related request.

On commit, a pending WlBuffer is applied first, and all other state second. This means that all coordinates in double-buffered state are relative to the new WlBuffer coming into use, except for WlSurface.attach() itself. If there is no pending WlBuffer, the coordinates are relative to the current surface contents.

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)¶

Request – opcode 7 (attached to Resource instance)

Sets the buffer transformation

This request sets an optional transformation on how the compositor interprets the contents of the buffer attached to the surface. The accepted values for the transform parameter are the values for WlOutput.transform().

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)¶

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 positive the invalid_scale protocol error is raised.

Parameters:	scale (ArgumentType.Int) – positive scale for interpreting buffer contents

damage_buffer(x, y, width, height)¶

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 WpViewport 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

enter(output)¶

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)¶

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.

Parameters:	output (`WlOutput`) – output left by the surface

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()¶

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.

Returns:	`WlPointer` – seat pointer

get_keyboard()¶

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.

Returns:	`WlKeyboard` – seat keyboard

get_touch()¶

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.

Returns:	`WlTouch` – seat touch interface

release()¶

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)¶

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)¶

Event – opcode 1 (attached to Proxy instance)

Unique identifier for this seat

In a multiseat configuration this can be used by the client to help identify which physical devices the seat represents. Based on the seat configuration used by the compositor.

Parameters:	name (ArgumentType.String) – seat identifier

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.

At connection setup time, the WlShm object emits one or more format events to inform clients about the valid pixel formats that can be used for buffers.

create_pool(fd, size)¶

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

format(format)¶

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

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)¶

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, serial)¶

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, serial, edges)¶

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()¶

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, x, y, flags)¶

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, framerate, output)¶

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, serial, parent, x, y, flags)¶

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)¶

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)¶

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_)¶

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)¶

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, width, height)¶

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()¶

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.

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 XdgShell.

get_shell_surface(surface)¶

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

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()¶

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 the event serial.

Returns:	`WlCallback` – callback object for the sync request

get_registry()¶

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, code, message)¶

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)¶

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

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, width, height, stride, format)¶

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()¶

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)¶

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.

Parameters:	size (ArgumentType.Int) – new size of the pool, in bytes

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()¶

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()¶

Request – opcode 1 (attached to Resource instance)

Create new region

Ask the compositor to create a new region.

Returns:	`WlRegion` – the new region

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()¶

Request – opcode 0 (attached to Resource instance)

Destroy region

Destroy the region. This will invalidate the object ID.

add(x, y, width, height)¶

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, y, width, height)¶

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

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()¶

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, y, physical_width, physical_height, subpixel, make, model, transform)¶

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).

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 xdg_output.name and xdg_output.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) – transform that maps framebuffer to output

mode(flags, width, height, refresh)¶

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.

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).

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()¶

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)¶

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. 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.

It is intended that scaling aware clients track the current output of a surface, and if it is on a scaled output it should use WlSurface.set_buffer_scale() with the scale of the output. That way the compositor can avoid scaling the surface, and the client can supply a higher detail image.

Parameters:	factor (ArgumentType.Int) – scaling factor of output

WlKeyboard¶

class pywayland.protocol.wayland.WlKeyboard¶

Keyboard input device

The WlKeyboard interface represents one or more keyboards associated with a seat.

release()¶

Request – opcode 0 (attached to Resource instance)

Release the keyboard object

keymap(format, fd, size)¶

Event – opcode 0 (attached to Proxy instance)

Keyboard mapping

This event provides a file descriptor to the client which can be memory-mapped 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, surface, keys)¶

Event – opcode 1 (attached to Proxy instance)

Enter event

Notification that this seat’s keyboard focus is on a certain surface.

Parameters:	serial (ArgumentType.Uint) – serial number of the enter event surface (`WlSurface`) – surface gaining keyboard focus keys (ArgumentType.Array) – the currently pressed keys

leave(serial, surface)¶

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.

Parameters:	serial (ArgumentType.Uint) – serial number of the leave event surface (`WlSurface`) – surface that lost keyboard focus

key(serial, time, key, state)¶

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.

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, mods_depressed, mods_latched, mods_locked, group)¶

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.

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, delay)¶

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

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, interface, version)¶

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, interface, version)¶

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)¶

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

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, surface, hotspot_x, hotspot_y)¶

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 surface.attach requests to the pointer surface, hotspot_x and hotspot_y are decremented by the x and y parameters passed to the request. Attach must be confirmed by 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 current and pending input regions of the WlSurface are cleared, and WlSurface.set_input_region() is ignored until the WlSurface is no longer used as the cursor. When the use as a cursor ends, the current and pending input regions become undefined, and the WlSurface is unmapped.

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()¶

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, surface, surface_x, surface_y)¶

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, surface)¶

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, surface_x, surface_y)¶

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, time, button, state)¶

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, axis, value)¶

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()¶

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)¶

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, axis)¶

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, discrete)¶

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 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.

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

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, mime_type)¶

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, fd)¶

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()¶

Request – opcode 2 (attached to Resource instance)

Destroy data offer

Destroy the data offer.

finish()¶

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, preferred_action)¶

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)¶

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)¶

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 right after WlDataDevice.enter(), 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)¶

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

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 have also other 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.

If the WlSurface associated with the WlSubsurface is destroyed, the WlSubsurface object becomes inert. Note, that destroying either object 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.

destroy()¶

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, and the WlSurface loses its role as a sub- surface. The WlSurface is unmapped immediately.

set_position(x, y)¶

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. When this happens depends on whether the parent surface is in synchronized mode or not. See WlSubsurface.set_sync() and WlSubsurface.set_desync() for details.

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)¶

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. When this happens depends on whether the parent surface is in synchronized mode or not. See WlSubsurface.set_sync() and WlSubsurface.set_desync() for details.

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)¶

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()¶

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()¶

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.

wp_primary_selection_unstable_v1 Module¶

ZwpPrimarySelectionDeviceV1¶

class pywayland.protocol.wp_primary_selection_unstable_v1.ZwpPrimarySelectionDeviceV1¶

set_selection(source, serial)¶

Request – opcode 0 (attached to Resource instance)

Set the primary selection

Replaces the current selection. The previous owner of the primary selection will receive a wp_primary_selection_source.cancelled event.

To unset the selection, set the source to NULL.

Parameters:	source (`ZwpPrimarySelectionSourceV1` or None) – serial (ArgumentType.Uint) – serial of the event that triggered this request

destroy()¶

Request – opcode 1 (attached to Resource instance)

Destroy the primary selection device

Destroy the primary selection device.

data_offer(offer)¶

Event – opcode 0 (attached to Proxy instance)

Introduce a new wp_primary_selection_offer

Introduces a new wp_primary_selection_offer object that may be used to receive the current primary selection. Immediately following this event, the new wp_primary_selection_offer object will send wp_primary_selection_offer.offer events to describe the offered mime types.

Parameters:	offer (`ZwpPrimarySelectionOfferV1`) –

selection(id)¶

Event – opcode 1 (attached to Proxy instance)

Advertise a new primary selection

The wp_primary_selection_device.selection event is sent to notify the client of a new primary selection. This event is sent after the wp_primary_selection.data_offer event introducing this object, and after the offer has announced its mimetypes through wp_primary_selection_offer.offer.

The data_offer is valid until a new offer or NULL is received or until the client loses keyboard focus. The client must destroy the previous selection data_offer, if any, upon receiving this event.

Parameters:	id (`ZwpPrimarySelectionOfferV1` or None) –

ZwpPrimarySelectionDeviceManagerV1¶

class pywayland.protocol.wp_primary_selection_unstable_v1.ZwpPrimarySelectionDeviceManagerV1¶

X primary selection emulation

The primary selection device manager is a singleton global object that provides access to the primary selection. It allows to create wp_primary_selection_source objects, as well as retrieving the per-seat wp_primary_selection_device objects.

create_source()¶

Request – opcode 0 (attached to Resource instance)

Create a new primary selection source

Create a new primary selection source.

Returns:	`ZwpPrimarySelectionSourceV1`

get_device(seat)¶

Request – opcode 1 (attached to Resource instance)

Create a new primary selection device

Create a new data device for a given seat.

Parameters:	seat (`WlSeat`) –
Returns:	`ZwpPrimarySelectionDeviceV1`

destroy()¶

Request – opcode 2 (attached to Resource instance)

Destroy the primary selection device manager

Destroy the primary selection device manager.

ZwpPrimarySelectionSourceV1¶

class pywayland.protocol.wp_primary_selection_unstable_v1.ZwpPrimarySelectionSourceV1¶

Offer to replace the contents of the primary selection

The source side of a wp_primary_selection_offer, it provides a way to describe the offered data and respond to requests to transfer the requested contents of the primary selection clipboard.

offer(mime_type)¶

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) –

destroy()¶

Request – opcode 1 (attached to Resource instance)

Destroy the primary selection source

Destroy the primary selection source.

send(mime_type, fd)¶

Event – opcode 0 (attached to Proxy instance)

Send the primary selection contents

Request for the current primary selection contents from the client. Send the specified mime type over the passed file descriptor, then close it.

Parameters:	mime_type (ArgumentType.String) – fd (ArgumentType.FileDescriptor) –

cancelled()¶

Event – opcode 1 (attached to Proxy instance)

Request for primary selection contents was canceled

This primary selection source is no longer valid. The client should clean up and destroy this primary selection source.

ZwpPrimarySelectionOfferV1¶

class pywayland.protocol.wp_primary_selection_unstable_v1.ZwpPrimarySelectionOfferV1¶

Offer to transfer primary selection contents

A wp_primary_selection_offer represents an offer to transfer the contents of the primary selection clipboard to the client. Similar to WlDataOffer, the offer also describes the mime types that the data can be converted to and provides the mechanisms for transferring the data directly to the client.

receive(mime_type, fd)¶

Request – opcode 0 (attached to Resource instance)

Request that the data is transferred

To transfer the contents of the primary selection clipboard, the client issues this request and indicates the mime type that 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 closes its end, at which point the transfer is complete.

Parameters:	mime_type (ArgumentType.String) – fd (ArgumentType.FileDescriptor) –

destroy()¶

Request – opcode 1 (attached to Resource instance)

Destroy the primary selection offer

Destroy the primary selection offer.

offer(mime_type)¶

Event – opcode 0 (attached to Proxy instance)

Advertise offered mime type

Sent immediately after creating announcing the wp_primary_selection_offer through wp_primary_selection_device.data_offer. One event is sent per offered mime type.

Parameters:	mime_type (ArgumentType.String) –

xdg_decoration_unstable_v1 Module¶

ZxdgDecorationManagerV1¶

class pywayland.protocol.xdg_decoration_unstable_v1.ZxdgDecorationManagerV1¶

Window decoration manager

This interface allows a compositor to announce support for server-side decorations.

A window decoration is a set of window controls as deemed appropriate by the party managing them, such as user interface components used to move, resize and change a window’s state.

A client can use this protocol to request being decorated by a supporting compositor.

If compositor and client do not negotiate the use of a server-side decoration using this protocol, clients continue to self-decorate as they see fit.

Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes are done by bumping the version number in the protocol and interface names and resetting the interface version. Once the protocol is to be declared stable, the ‘z’ prefix and the version number in the protocol and interface names are removed and the interface version number is reset.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the decoration manager object

Destroy the decoration manager. This doesn’t destroy objects created with the manager.

get_toplevel_decoration(toplevel)¶

Request – opcode 1 (attached to Resource instance)

Create a new toplevel decoration object

Create a new decoration object associated with the given toplevel.

Creating an xdg_toplevel_decoration from an XdgToplevel which has a buffer attached or committed is a client error, and any attempts by a client to attach or manipulate a buffer prior to the first xdg_toplevel_decoration.configure event must also be treated as errors.

Parameters:	toplevel (`XdgToplevel`) –
Returns:	`ZxdgToplevelDecorationV1`

ZxdgToplevelDecorationV1¶

class pywayland.protocol.xdg_decoration_unstable_v1.ZxdgToplevelDecorationV1¶

Decoration object for a toplevel surface

The decoration object allows the compositor to toggle server-side window decorations for a toplevel surface. The client can request to switch to another mode.

The xdg_toplevel_decoration object must be destroyed before its XdgToplevel.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the decoration object

Switch back to a mode without any server-side decorations at the next commit.

set_mode(mode)¶

Request – opcode 1 (attached to Resource instance)

Set the decoration mode

Set the toplevel surface decoration mode. This informs the compositor that the client prefers the provided decoration mode.

After requesting a decoration mode, the compositor will respond by emitting a XdgSurface.configure() event. The client should then update its content, drawing it without decorations if the received mode is server-side decorations. The client must also acknowledge the configure when committing the new content (see XdgSurface.ack_configure()).

The compositor can decide not to use the client’s mode and enforce a different mode instead.

Clients whose decoration mode depend on the XdgToplevel state may send a set_mode request in response to a XdgSurface.configure() event and wait for the next XdgSurface.configure() event to prevent unwanted state. Such clients are responsible for preventing configure loops and must make sure not to send multiple successive set_mode requests with the same decoration mode.

Parameters:	mode (ArgumentType.Uint) – the decoration mode

unset_mode()¶

Request – opcode 2 (attached to Resource instance)

Unset the decoration mode

Unset the toplevel surface decoration mode. This informs the compositor that the client doesn’t prefer a particular decoration mode.

This request has the same semantics as set_mode.

configure(mode)¶

Event – opcode 0 (attached to Proxy instance)

Suggest a surface change

The configure event asks the client to change its decoration mode. The configured state should not be applied immediately. Clients must send an ack_configure in response to this event. See XdgSurface.configure() and XdgSurface.ack_configure() for details.

A configure event can be sent at any time. The specified mode must be obeyed by the client.

Parameters:	mode (ArgumentType.Uint) – the decoration mode

xdg_foreign_unstable_v1 Module¶

ZxdgExportedV1¶

class pywayland.protocol.xdg_foreign_unstable_v1.ZxdgExportedV1¶

An exported surface handle

A xdg_exported object represents an exported reference to a surface. The exported surface may be referenced as long as the xdg_exported object not destroyed. Destroying the xdg_exported invalidates any relationship the importer may have established using xdg_imported.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Unexport the exported surface

Revoke the previously exported surface. This invalidates any relationship the importer may have set up using the xdg_imported created given the handle sent via xdg_exported.handle.

handle(handle)¶

Event – opcode 0 (attached to Proxy instance)

The exported surface handle

The handle event contains the unique handle of this exported surface reference. It may be shared with any client, which then can use it to import the surface by calling xdg_importer.import. A handle may be used to import the surface multiple times.

Parameters:	handle (ArgumentType.String) – the exported surface handle

ZxdgImportedV1¶

class pywayland.protocol.xdg_foreign_unstable_v1.ZxdgImportedV1¶

An imported surface handle

A xdg_imported object represents an imported reference to surface exported by some client. A client can use this interface to manipulate relationships between its own surfaces and the imported surface.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the xdg_imported object

Notify the compositor that it will no longer use the xdg_imported object. Any relationship that may have been set up will at this point be invalidated.

set_parent_of(surface)¶

Request – opcode 1 (attached to Resource instance)

Set as the parent of some surface

Set the imported surface as the parent of some surface of the client. The passed surface must be a toplevel XdgSurface. Calling this function sets up a surface to surface relation with the same stacking and positioning semantics as XdgSurface.set_parent().

Parameters:	surface (`WlSurface`) – the child surface

destroyed()¶

Event – opcode 0 (attached to Proxy instance)

The imported surface handle has been destroyed

The imported surface handle has been destroyed and any relationship set up has been invalidated. This may happen for various reasons, for example if the exported surface or the exported surface handle has been destroyed, if the handle used for importing was invalid.

ZxdgExporterV1¶

class pywayland.protocol.xdg_foreign_unstable_v1.ZxdgExporterV1¶

Interface for exporting surfaces

A global interface used for exporting surfaces that can later be imported using xdg_importer.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the xdg_exporter object

Notify the compositor that the xdg_exporter object will no longer be used.

export(surface)¶

Request – opcode 1 (attached to Resource instance)

Export a surface

The export request exports the passed surface so that it can later be imported via xdg_importer. When called, a new xdg_exported object will be created and xdg_exported.handle will be sent immediately. See the corresponding interface and event for details.

A surface may be exported multiple times, and each exported handle may be used to create a xdg_imported multiple times. Only XdgSurface surfaces may be exported.

Parameters:	surface (`WlSurface`) – the surface to export
Returns:	`ZxdgExportedV1` – the new xdg_exported object

ZxdgImporterV1¶

class pywayland.protocol.xdg_foreign_unstable_v1.ZxdgImporterV1¶

Interface for importing surfaces

A global interface used for importing surfaces exported by xdg_exporter. With this interface, a client can create a reference to a surface of another client.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the xdg_importer object

Notify the compositor that the xdg_importer object will no longer be used.

import_(handle)¶

Request – opcode 1 (attached to Resource instance)

Import a surface

The import request imports a surface from any client given a handle retrieved by exporting said surface using xdg_exporter.export. When called, a new xdg_imported object will be created. This new object represents the imported surface, and the importing client can manipulate its relationship using it. See xdg_imported for details.

Parameters:	handle (ArgumentType.String) – the exported surface handle
Returns:	`ZxdgImportedV1` – the new xdg_imported object

xdg_foreign_unstable_v2 Module¶

ZxdgImporterV2¶

class pywayland.protocol.xdg_foreign_unstable_v2.ZxdgImporterV2¶

Interface for importing surfaces

A global interface used for importing surfaces exported by xdg_exporter. With this interface, a client can create a reference to a surface of another client.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the xdg_importer object

Notify the compositor that the xdg_importer object will no longer be used.

import_toplevel(handle)¶

Request – opcode 1 (attached to Resource instance)

Import a toplevel surface

The import_toplevel request imports a surface from any client given a handle retrieved by exporting said surface using xdg_exporter.export_toplevel. When called, a new xdg_imported object will be created. This new object represents the imported surface, and the importing client can manipulate its relationship using it. See xdg_imported for details.

Parameters:	handle (ArgumentType.String) – the exported surface handle
Returns:	`ZxdgImportedV2` – the new xdg_imported object

ZxdgExportedV2¶

class pywayland.protocol.xdg_foreign_unstable_v2.ZxdgExportedV2¶

An exported surface handle

A xdg_exported object represents an exported reference to a surface. The exported surface may be referenced as long as the xdg_exported object not destroyed. Destroying the xdg_exported invalidates any relationship the importer may have established using xdg_imported.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Unexport the exported surface

Revoke the previously exported surface. This invalidates any relationship the importer may have set up using the xdg_imported created given the handle sent via xdg_exported.handle.

handle(handle)¶

Event – opcode 0 (attached to Proxy instance)

The exported surface handle

The handle event contains the unique handle of this exported surface reference. It may be shared with any client, which then can use it to import the surface by calling xdg_importer.import_toplevel. A handle may be used to import the surface multiple times.

Parameters:	handle (ArgumentType.String) – the exported surface handle

ZxdgExporterV2¶

class pywayland.protocol.xdg_foreign_unstable_v2.ZxdgExporterV2¶

Interface for exporting surfaces

A global interface used for exporting surfaces that can later be imported using xdg_importer.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the xdg_exporter object

Notify the compositor that the xdg_exporter object will no longer be used.

export_toplevel(surface)¶

Request – opcode 1 (attached to Resource instance)

Export a toplevel surface

The export_toplevel request exports the passed surface so that it can later be imported via xdg_importer. When called, a new xdg_exported object will be created and xdg_exported.handle will be sent immediately. See the corresponding interface and event for details.

A surface may be exported multiple times, and each exported handle may be used to create a xdg_imported multiple times. Only XdgToplevel equivalent surfaces may be exported.

Parameters:	surface (`WlSurface`) – the surface to export
Returns:	`ZxdgExportedV2` – the new xdg_exported object

ZxdgImportedV2¶

class pywayland.protocol.xdg_foreign_unstable_v2.ZxdgImportedV2¶

An imported surface handle

A xdg_imported object represents an imported reference to surface exported by some client. A client can use this interface to manipulate relationships between its own surfaces and the imported surface.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the xdg_imported object

Notify the compositor that it will no longer use the xdg_imported object. Any relationship that may have been set up will at this point be invalidated.

set_parent_of(surface)¶

Request – opcode 1 (attached to Resource instance)

Set as the parent of some surface

Set the imported surface as the parent of some surface of the client. The passed surface must be a XdgToplevel equivalent. Calling this function sets up a surface to surface relation with the same stacking and positioning semantics as XdgToplevel.set_parent().

Parameters:	surface (`WlSurface`) – the child surface

destroyed()¶

Event – opcode 0 (attached to Proxy instance)

The imported surface handle has been destroyed

The imported surface handle has been destroyed and any relationship set up has been invalidated. This may happen for various reasons, for example if the exported surface or the exported surface handle has been destroyed, if the handle used for importing was invalid.

xdg_output_unstable_v1 Module¶

ZxdgOutputV1¶

class pywayland.protocol.xdg_output_unstable_v1.ZxdgOutputV1¶

Compositor logical output region

An xdg_output describes part of the compositor geometry.

This typically corresponds to a monitor that displays part of the compositor space.

For objects version 3 onwards, after all xdg_output properties have been sent (when the object is created and when properties are updated), a WlOutput.done() event is sent. This allows changes to the output properties to be seen as atomic, even if they happen via multiple events.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the xdg_output object

Using this request a client can tell the server that it is not going to use the xdg_output object anymore.

logical_position(x, y)¶

Event – opcode 0 (attached to Proxy instance)

Position of the output within the global compositor space

The position event describes the location of the WlOutput within the global compositor space.

The logical_position event is sent after creating an xdg_output (see xdg_output_manager.get_xdg_output) and whenever the location of the output changes within the global compositor space.

Parameters:	x (ArgumentType.Int) – x position within the global compositor space y (ArgumentType.Int) – y position within the global compositor space

logical_size(width, height)¶

Event – opcode 1 (attached to Proxy instance)

Size of the output in the global compositor space

The logical_size event describes the size of the output in the global compositor space.

For example, a surface without any buffer scale, transformation nor rotation set, with the size matching the logical_size will have the same size as the corresponding output when displayed.

Most regular Wayland clients should not pay attention to the logical size and would rather rely on XdgShell interfaces.

Some clients such as Xwayland, however, need this to configure their surfaces in the global compositor space as the compositor may apply a different scale from what is advertised by the output scaling property (to achieve fractional scaling, for example).

For example, for a WlOutput mode 3840×2160 and a scale factor 2:

A compositor not scaling the surface buffers will advertise a logical size of 3840×2160,
A compositor automatically scaling the surface buffers will advertise a logical size of 1920×1080,
A compositor using a fractional scale of 1.5 will advertise a logical size to 2560×1620.

For example, for a WlOutput mode 1920×1080 and a 90 degree rotation, the compositor will advertise a logical size of 1080x1920.

The logical_size event is sent after creating an xdg_output (see xdg_output_manager.get_xdg_output) and whenever the logical size of the output changes, either as a result of a change in the applied scale or because of a change in the corresponding output mode(see WlOutput.mode()) or transform (see WlOutput.transform()).

Parameters:	width (ArgumentType.Int) – width in global compositor space height (ArgumentType.Int) – height in global compositor space

done()¶

Event – opcode 2 (attached to Proxy instance)

All information about the output have been sent

This event is sent after all other properties of an xdg_output have been sent.

This allows changes to the xdg_output properties to be seen as atomic, even if they happen via multiple events.

For objects version 3 onwards, this event is deprecated. Compositors are not required to send it anymore and must send WlOutput.done() instead.

name(name)¶

Event – opcode 3 (attached to Proxy instance)

Name of this output

Many compositors will assign names to their outputs, show them to the user, allow them to be configured by name, etc. The client may wish to know this name as well to offer the user similar behaviors.

The naming convention is compositor defined, but limited to alphanumeric characters and dashes (-). Each name is unique among all WlOutput globals, but if a WlOutput global is destroyed the same name may be reused later. The names will also remain consistent across sessions with the same hardware and software configuration.

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 creating an xdg_output (see xdg_output_manager.get_xdg_output). This event is only sent once per xdg_output, and the name does not change over the lifetime of the WlOutput global.

Parameters:	name (ArgumentType.String) – output name

description(description)¶

Event – opcode 4 (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, to communicate the user for various purposes.

The description is a UTF-8 string with no convention defined for its contents. Examples might include ‘Foocorp 11” Display’ or ‘Virtual X11 output via :1’.

The description event is sent after creating an xdg_output (see xdg_output_manager.get_xdg_output) and whenever the description changes. The description is optional, and may not be sent at all.

For objects of version 2 and lower, this event is only sent once per xdg_output, and the description does not change over the lifetime of the WlOutput global.

Parameters:	description (ArgumentType.String) – output description

ZxdgOutputManagerV1¶

class pywayland.protocol.xdg_output_unstable_v1.ZxdgOutputManagerV1¶

Manage xdg_output objects

A global factory interface for xdg_output objects.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the xdg_output_manager object

Using this request a client can tell the server that it is not going to use the xdg_output_manager object anymore.

Any objects already created through this instance are not affected.

get_xdg_output(output)¶

Request – opcode 1 (attached to Resource instance)

Create an xdg output from a WlOutput

This creates a new xdg_output object for the given WlOutput.

Parameters:	output (`WlOutput`) –
Returns:	`ZxdgOutputV1`

xdg_shell Module¶

XdgPositioner¶

class pywayland.protocol.xdg_shell.XdgPositioner¶

Child surface positioner

The XdgPositioner provides a collection of rules for the placement of a child surface relative to a parent surface. Rules can be defined to ensure the child surface remains within the visible area’s borders, and to specify how the child surface changes its position, such as sliding along an axis, or flipping around a rectangle. These positioner-created rules are constrained by the requirement that a child surface must intersect with or be at least partially adjacent to its parent surface.

See the various requests for details about possible rules.

At the time of the request, the compositor makes a copy of the rules specified by the XdgPositioner. Thus, after the request is complete the XdgPositioner object can be destroyed or reused; further changes to the object will have no effect on previous usages.

For an XdgPositioner object to be considered complete, it must have a non-zero size set by set_size, and a non-zero anchor rectangle set by set_anchor_rect. Passing an incomplete XdgPositioner object when positioning a surface raises an error.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the XdgPositioner object

Notify the compositor that the XdgPositioner will no longer be used.

set_size(width, height)¶

Request – opcode 1 (attached to Resource instance)

Set the size of the to-be positioned rectangle

Set the size of the surface that is to be positioned with the positioner object. The size is in surface-local coordinates and corresponds to the window geometry. See XdgSurface.set_window_geometry().

If a zero or negative size is set the invalid_input error is raised.

Parameters:	width (ArgumentType.Int) – width of positioned rectangle height (ArgumentType.Int) – height of positioned rectangle

set_anchor_rect(x, y, width, height)¶

Request – opcode 2 (attached to Resource instance)

Set the anchor rectangle within the parent surface

Specify the anchor rectangle within the parent surface that the child surface will be placed relative to. The rectangle is relative to the window geometry as defined by XdgSurface.set_window_geometry() of the parent surface.

When the XdgPositioner object is used to position a child surface, the anchor rectangle may not extend outside the window geometry of the positioned child’s parent surface.

If a negative size is set the invalid_input error is raised.

Parameters:	x (ArgumentType.Int) – x position of anchor rectangle y (ArgumentType.Int) – y position of anchor rectangle width (ArgumentType.Int) – width of anchor rectangle height (ArgumentType.Int) – height of anchor rectangle

set_anchor(anchor)¶

Request – opcode 3 (attached to Resource instance)

Set anchor rectangle anchor

Defines the anchor point for the anchor rectangle. The specified anchor is used derive an anchor point that the child surface will be positioned relative to. If a corner anchor is set (e.g. ‘top_left’ or ‘bottom_right’), the anchor point will be at the specified corner; otherwise, the derived anchor point will be centered on the specified edge, or in the center of the anchor rectangle if no edge is specified.

Parameters:	anchor (ArgumentType.Uint) – anchor

set_gravity(gravity)¶

Request – opcode 4 (attached to Resource instance)

Set child surface gravity

Defines in what direction a surface should be positioned, relative to the anchor point of the parent surface. If a corner gravity is specified (e.g. ‘bottom_right’ or ‘top_left’), then the child surface will be placed towards the specified gravity; otherwise, the child surface will be centered over the anchor point on any axis that had no gravity specified.

Parameters:	gravity (ArgumentType.Uint) – gravity direction

set_constraint_adjustment(constraint_adjustment)¶

Request – opcode 5 (attached to Resource instance)

Set the adjustment to be done when constrained

Specify how the window should be positioned if the originally intended position caused the surface to be constrained, meaning at least partially outside positioning boundaries set by the compositor. The adjustment is set by constructing a bitmask describing the adjustment to be made when the surface is constrained on that axis.

If no bit for one axis is set, the compositor will assume that the child surface should not change its position on that axis when constrained.

If more than one bit for one axis is set, the order of how adjustments are applied is specified in the corresponding adjustment descriptions.

The default adjustment is none.

Parameters:	constraint_adjustment (ArgumentType.Uint) – bit mask of constraint adjustments

set_offset(x, y)¶

Request – opcode 6 (attached to Resource instance)

Set surface position offset

Specify the surface position offset relative to the position of the anchor on the anchor rectangle and the anchor on the surface. For example if the anchor of the anchor rectangle is at (x, y), the surface has the gravity bottom|right, and the offset is (ox, oy), the calculated surface position will be (x + ox, y + oy). The offset position of the surface is the one used for constraint testing. See set_constraint_adjustment.

An example use case is placing a popup menu on top of a user interface element, while aligning the user interface element of the parent surface with some user interface element placed somewhere in the popup surface.

Parameters:	x (ArgumentType.Int) – surface position x offset y (ArgumentType.Int) – surface position y offset

set_reactive()¶

Request – opcode 7 (attached to Resource instance)

Continuously reconstrain the surface

When set reactive, the surface is reconstrained if the conditions used for constraining changed, e.g. the parent window moved.

If the conditions changed and the popup was reconstrained, an XdgPopup.configure() event is sent with updated geometry, followed by an XdgSurface.configure() event.

set_parent_size(parent_width, parent_height)¶

Request – opcode 8 (attached to Resource instance)

Set the parent window geometry the compositor should use when positioning the popup. The compositor may use this information to determine the future state the popup should be constrained using. If this doesn’t match the dimension of the parent the popup is eventually positioned against, the behavior is undefined.

The arguments are given in the surface-local coordinate space.

Parameters:	parent_width (ArgumentType.Int) – future window geometry width of parent parent_height (ArgumentType.Int) – future window geometry height of parent

set_parent_configure(serial)¶

Request – opcode 9 (attached to Resource instance)

Set parent configure this is a response to

Set the serial of a XdgSurface.configure() event this positioner will be used in response to. The compositor may use this information together with set_parent_size to determine what future state the popup should be constrained using.

Parameters:	serial (ArgumentType.Uint) – serial of parent configure event

XdgToplevel¶

class pywayland.protocol.xdg_shell.XdgToplevel¶

Toplevel surface

This interface defines an XdgSurface role which allows a surface to, among other things, set window-like properties such as maximize, fullscreen, and minimize, set application- specific metadata like title and id, and well as trigger user interactive operations such as interactive resize and move.

Unmapping an XdgToplevel means that the surface cannot be shown by the compositor until it is explicitly mapped again. All active operations (e.g., move, resize) are canceled and all attributes (e.g. title, state, stacking, …) are discarded for an XdgToplevel surface when it is unmapped.

Attaching a null buffer to a toplevel unmaps the surface.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the XdgToplevel

This request destroys the role surface and unmaps the surface; see “Unmapping” behavior in interface section for details.

set_parent(parent)¶

Request – opcode 1 (attached to Resource instance)

Set the parent of this surface

Set the “parent” of this surface. This surface should be stacked above the parent surface and all other ancestor surfaces.

Parent windows should be set on dialogs, toolboxes, or other “auxiliary” surfaces, so that the parent is raised when the dialog is raised.

Setting a null parent for a child window removes any parent-child relationship for the child. Setting a null parent for a window which currently has no parent is a no-op.

If the parent is unmapped then its children are managed as though the parent of the now-unmapped parent has become the parent of this surface. If no parent exists for the now-unmapped parent then the children are managed as though they have no parent surface.

Parameters:	parent (`XdgToplevel` or None) –

set_title(title)¶

Request – opcode 2 (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) –

set_app_id(app_id)¶

Request – opcode 3 (attached to Resource instance)

Set application id

Set an application identifier for the surface.

The app ID identifies the general class of applications to which the surface belongs. The compositor can use this to group multiple surfaces together, or to determine how to launch a new application.

For D-Bus activatable applications, the app ID is used as the D-Bus service name.

The compositor shell will try to group application surfaces together by their app ID. As a best practice, it is suggested to select app ID’s that match the basename of the application’s .desktop file. For example, “org.freedesktop.FooViewer” where the .desktop file is “org.freedesktop.FooViewer.desktop”.

Like other properties, a set_app_id request can be sent after the XdgToplevel has been mapped to update the property.

See the desktop-entry specification [0] for more details on application identifiers and how they relate to well-known D-Bus names and .desktop files.

[0] http://standards.freedesktop.org/desktop-entry-spec/

Parameters:	app_id (ArgumentType.String) –

show_window_menu(seat, serial, x, y)¶

Request – opcode 4 (attached to Resource instance)

Show the window menu

Clients implementing client-side decorations might want to show a context menu when right-clicking on the decorations, giving the user a menu that they can use to maximize or minimize the window.

This request asks the compositor to pop up such a window menu at the given position, relative to the local surface coordinates of the parent surface. There are no guarantees as to what menu items the window menu contains.

This request must be used in response to some sort of user action like a button press, key press, or touch down event.

Parameters:	seat (`WlSeat`) – the `WlSeat` of the user event serial (ArgumentType.Uint) – the serial of the user event x (ArgumentType.Int) – the x position to pop up the window menu at y (ArgumentType.Int) – the y position to pop up the window menu at

move(seat, serial)¶

Request – opcode 5 (attached to Resource instance)

Start an interactive move

Start an interactive, user-driven move of the surface.

This request must be used in response to some sort of user action like a button press, key press, or touch down event. The passed serial is used to determine the type of interactive move (touch, pointer, etc).

The server may ignore move requests depending on the state of the surface (e.g. fullscreen or maximized), or if the passed serial is no longer valid.

If triggered, the surface will lose the focus of the device (WlPointer, WlTouch, etc) used for the move. It is up to the compositor to visually indicate that the move is taking place, such as updating a pointer cursor, during the move. There is no guarantee that the device focus will return when the move is completed.

Parameters:	seat (`WlSeat`) – the `WlSeat` of the user event serial (ArgumentType.Uint) – the serial of the user event

resize(seat, serial, edges)¶

Request – opcode 6 (attached to Resource instance)

Start an interactive resize

Start a user-driven, interactive resize of the surface.

This request must be used in response to some sort of user action like a button press, key press, or touch down event. The passed serial is used to determine the type of interactive resize (touch, pointer, etc).

The server may ignore resize requests depending on the state of the surface (e.g. fullscreen or maximized).

If triggered, the client will receive configure events with the “resize” state enum value and the expected sizes. See the “resize” enum value for more details about what is required. The client must also acknowledge configure events using “ack_configure”. After the resize is completed, the client will receive another “configure” event without the resize state.

If triggered, the surface also will lose the focus of the device (WlPointer, WlTouch, etc) used for the resize. It is up to the compositor to visually indicate that the resize is taking place, such as updating a pointer cursor, during the resize. There is no guarantee that the device focus will return when the resize is completed.

The edges parameter specifies how the surface should be resized, and is one of the values of the resize_edge enum. The compositor may use this information to update the surface position for example when dragging the top left corner. The compositor may also use this information to adapt its behavior, e.g. choose an appropriate cursor image.

Parameters:	seat (`WlSeat`) – the `WlSeat` of the user event serial (ArgumentType.Uint) – the serial of the user event edges (ArgumentType.Uint) – which edge or corner is being dragged

set_max_size(width, height)¶

Request – opcode 7 (attached to Resource instance)

Set the maximum size

Set a maximum size for the window.

The client can specify a maximum size so that the compositor does not try to configure the window beyond this size.

The width and height arguments are in window geometry coordinates. See XdgSurface.set_window_geometry().

Values set in this way are double-buffered. They will get applied on the next commit.

The compositor can use this information to allow or disallow different states like maximize or fullscreen and draw accurate animations.

Similarly, a tiling window manager may use this information to place and resize client windows in a more effective way.

The client should not rely on the compositor to obey the maximum size. The compositor may decide to ignore the values set by the client and request a larger size.

If never set, or a value of zero in the request, means that the client has no expected maximum size in the given dimension. As a result, a client wishing to reset the maximum size to an unspecified state can use zero for width and height in the request.

Requesting a maximum size to be smaller than the minimum size of a surface is illegal and will result in a protocol error.

The width and height must be greater than or equal to zero. Using strictly negative values for width and height will result in a protocol error.

Parameters:	width (ArgumentType.Int) – height (ArgumentType.Int) –

set_min_size(width, height)¶

Request – opcode 8 (attached to Resource instance)

Set the minimum size

Set a minimum size for the window.

The client can specify a minimum size so that the compositor does not try to configure the window below this size.

The width and height arguments are in window geometry coordinates. See XdgSurface.set_window_geometry().

Values set in this way are double-buffered. They will get applied on the next commit.

The compositor can use this information to allow or disallow different states like maximize or fullscreen and draw accurate animations.

Similarly, a tiling window manager may use this information to place and resize client windows in a more effective way.

The client should not rely on the compositor to obey the minimum size. The compositor may decide to ignore the values set by the client and request a smaller size.

If never set, or a value of zero in the request, means that the client has no expected minimum size in the given dimension. As a result, a client wishing to reset the minimum size to an unspecified state can use zero for width and height in the request.

Requesting a minimum size to be larger than the maximum size of a surface is illegal and will result in a protocol error.

The width and height must be greater than or equal to zero. Using strictly negative values for width and height will result in a protocol error.

Parameters:	width (ArgumentType.Int) – height (ArgumentType.Int) –

set_maximized()¶

Request – opcode 9 (attached to Resource instance)

Maximize the window

Maximize the surface.

After requesting that the surface should be maximized, the compositor will respond by emitting a configure event. Whether this configure actually sets the window maximized is subject to compositor policies. The client must then update its content, drawing in the configured state. The client must also acknowledge the configure when committing the new content (see ack_configure).

It is up to the compositor to decide how and where to maximize the surface, for example which output and what region of the screen should be used.

If the surface was already maximized, the compositor will still emit a configure event with the “maximized” state.

If the surface is in a fullscreen state, this request has no direct effect. It may alter the state the surface is returned to when unmaximized unless overridden by the compositor.

unset_maximized()¶

Request – opcode 10 (attached to Resource instance)

Unmaximize the window

Unmaximize the surface.

After requesting that the surface should be unmaximized, the compositor will respond by emitting a configure event. Whether this actually un- maximizes the window is subject to compositor policies. If available and applicable, the compositor will include the window geometry dimensions the window had prior to being maximized in the configure event. The client must then update its content, drawing it in the configured state. The client must also acknowledge the configure when committing the new content (see ack_configure).

It is up to the compositor to position the surface after it was unmaximized; usually the position the surface had before maximizing, if applicable.

If the surface was already not maximized, the compositor will still emit a configure event without the “maximized” state.

If the surface is in a fullscreen state, this request has no direct effect. It may alter the state the surface is returned to when unmaximized unless overridden by the compositor.

set_fullscreen(output)¶

Request – opcode 11 (attached to Resource instance)

Set the window as fullscreen on an output

Make the surface fullscreen.

After requesting that the surface should be fullscreened, the compositor will respond by emitting a configure event. Whether the client is actually put into a fullscreen state is subject to compositor policies. The client must also acknowledge the configure when committing the new content (see ack_configure).

The output passed by the request indicates the client’s preference as to which display it should be set fullscreen on. If this value is NULL, it’s up to the compositor to choose which display will be used to map this surface.

If the surface doesn’t cover the whole output, the compositor will position the surface in the center of the output and compensate with with border fill covering the rest of the output. The content of the border fill is undefined, but should be assumed to be in some way that attempts to blend into the surrounding area (e.g. solid black).

If the fullscreened surface is not opaque, the compositor must make sure that other screen content not part of the same surface tree (made up of subsurfaces, popups or similarly coupled surfaces) are not visible below the fullscreened surface.

Parameters:	output (`WlOutput` or None) –

unset_fullscreen()¶

Request – opcode 12 (attached to Resource instance)

Unset the window as fullscreen

Make the surface no longer fullscreen.

After requesting that the surface should be unfullscreened, the compositor will respond by emitting a configure event. Whether this actually removes the fullscreen state of the client is subject to compositor policies.

Making a surface unfullscreen sets states for the surface based on the following: * the state(s) it may have had before becoming fullscreen * any state(s) decided by the compositor * any state(s) requested by the client while the surface was fullscreen

The compositor may include the previous window geometry dimensions in the configure event, if applicable.

The client must also acknowledge the configure when committing the new content (see ack_configure).

set_minimized()¶

Request – opcode 13 (attached to Resource instance)

Set the window as minimized

Request that the compositor minimize your surface. There is no way to know if the surface is currently minimized, nor is there any way to unset minimization on this surface.

If you are looking to throttle redrawing when minimized, please instead use the WlSurface.frame() event for this, as this will also work with live previews on windows in Alt-Tab, Expose or similar compositor features.

configure(width, height, states)¶

Event – opcode 0 (attached to Proxy instance)

Suggest a surface change

This configure event asks the client to resize its toplevel surface or to change its state. The configured state should not be applied immediately. See XdgSurface.configure() for details.

The width and height arguments specify a hint to the window about how its surface should be resized in window geometry coordinates. See set_window_geometry.

If the width or height arguments are zero, it means the client should decide its own window dimension. This may happen when the compositor needs to configure the state of the surface but doesn’t have any information about any previous or expected dimension.

The states listed in the event specify how the width/height arguments should be interpreted, and possibly how it should be drawn.

Clients must send an ack_configure in response to this event. See XdgSurface.configure() and XdgSurface.ack_configure() for details.

Parameters:	width (ArgumentType.Int) – height (ArgumentType.Int) – states (ArgumentType.Array) –

close()¶

Event – opcode 1 (attached to Proxy instance)

Surface wants to be closed

The close event is sent by the compositor when the user wants the surface to be closed. This should be equivalent to the user clicking the close button in client-side decorations, if your application has any.

This is only a request that the user intends to close the window. The client may choose to ignore this request, or show a dialog to ask the user to save their data, etc.

XdgPopup¶

class pywayland.protocol.xdg_shell.XdgPopup¶

Short-lived, popup surfaces for menus

A popup surface is a short-lived, temporary surface. It can be used to implement for example menus, popovers, tooltips and other similar user interface concepts.

A popup can be made to take an explicit grab. See XdgPopup.grab() for details.

When the popup is dismissed, a popup_done event will be sent out, and at the same time the surface will be unmapped. See the XdgPopup.popup_done() event for details.

Explicitly destroying the XdgPopup object will also dismiss the popup and unmap the surface. Clients that want to dismiss the popup when another surface of their own is clicked should dismiss the popup using the destroy request.

A newly created XdgPopup will be stacked on top of all previously created XdgPopup surfaces associated with the same XdgToplevel.

The parent of an XdgPopup must be mapped (see the XdgSurface description) before the XdgPopup itself.

The client must call WlSurface.commit() on the corresponding WlSurface for the XdgPopup state to take effect.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Remove XdgPopup interface

This destroys the popup. Explicitly destroying the XdgPopup object will also dismiss the popup, and unmap the surface.

If this XdgPopup is not the “topmost” popup, a protocol error will be sent.

grab(seat, serial)¶

Request – opcode 1 (attached to Resource instance)

Make the popup take an explicit grab

This request makes the created popup take an explicit grab. An explicit grab will be dismissed when the user dismisses the popup, or when the client destroys the XdgPopup. This can be done by the user clicking outside the surface, using the keyboard, or even locking the screen through closing the lid or a timeout.

If the compositor denies the grab, the popup will be immediately dismissed.

This request must be used in response to some sort of user action like a button press, key press, or touch down event. The serial number of the event should be passed as ‘serial’.

The parent of a grabbing popup must either be an XdgToplevel surface or another XdgPopup with an explicit grab. If the parent is another XdgPopup it means that the popups are nested, with this popup now being the topmost popup.

Nested popups must be destroyed in the reverse order they were created in, e.g. the only popup you are allowed to destroy at all times is the topmost one.

When compositors choose to dismiss a popup, they may dismiss every nested grabbing popup as well. When a compositor dismisses popups, it will follow the same dismissing order as required from the client.

The parent of a grabbing popup must either be another XdgPopup with an active explicit grab, or an XdgPopup or XdgToplevel, if there are no explicit grabs already taken.

If the topmost grabbing popup is destroyed, the grab will be returned to the parent of the popup, if that parent previously had an explicit grab.

If the parent is a grabbing popup which has already been dismissed, this popup will be immediately dismissed. If the parent is a popup that did not take an explicit grab, an error will be raised.

During a popup grab, the client owning the grab will receive pointer and touch events for all their surfaces as normal (similar to an “owner-events” grab in X11 parlance), while the top most grabbing popup will always have keyboard focus.

Parameters:	seat (`WlSeat`) – the `WlSeat` of the user event serial (ArgumentType.Uint) – the serial of the user event

reposition(positioner, token)¶

Request – opcode 2 (attached to Resource instance)

Recalculate the popup’s location

Reposition an already-mapped popup. The popup will be placed given the details in the passed XdgPositioner object, and a XdgPopup.repositioned() followed by XdgPopup.configure() and XdgSurface.configure() will be emitted in response. Any parameters set by the previous positioner will be discarded.

The passed token will be sent in the corresponding XdgPopup.repositioned() event. The new popup position will not take effect until the corresponding configure event is acknowledged by the client. See XdgPopup.repositioned() for details. The token itself is opaque, and has no other special meaning.

If multiple reposition requests are sent, the compositor may skip all but the last one.

If the popup is repositioned in response to a configure event for its parent, the client should send an XdgPositioner.set_parent_configure() and possibly a XdgPositioner.set_parent_size() request to allow the compositor to properly constrain the popup.

If the popup is repositioned together with a parent that is being resized, but not in response to a configure event, the client should send a XdgPositioner.set_parent_size() request.

Parameters:	positioner (`XdgPositioner`) – token (ArgumentType.Uint) – reposition request token

configure(x, y, width, height)¶

Event – opcode 0 (attached to Proxy instance)

Configure the popup surface

This event asks the popup surface to configure itself given the configuration. The configured state should not be applied immediately. See XdgSurface.configure() for details.

The x and y arguments represent the position the popup was placed at given the XdgPositioner rule, relative to the upper left corner of the window geometry of the parent surface.

For version 2 or older, the configure event for an XdgPopup is only ever sent once for the initial configuration. Starting with version 3, it may be sent again if the popup is setup with an XdgPositioner with set_reactive requested, or in response to XdgPopup.reposition() requests.

Parameters:	x (ArgumentType.Int) – x position relative to parent surface window geometry y (ArgumentType.Int) – y position relative to parent surface window geometry width (ArgumentType.Int) – window geometry width height (ArgumentType.Int) – window geometry height

popup_done()¶

Event – opcode 1 (attached to Proxy instance)

Popup interaction is done

The popup_done event is sent out when a popup is dismissed by the compositor. The client should destroy the XdgPopup object at this point.

repositioned(token)¶

Event – opcode 2 (attached to Proxy instance)

Signal the completion of a repositioned request

The repositioned event is sent as part of a popup configuration sequence, together with XdgPopup.configure() and lastly XdgSurface.configure() to notify the completion of a reposition request.

The repositioned event is to notify about the completion of a XdgPopup.reposition() request. The token argument is the token passed in the XdgPopup.reposition() request.

Immediately after this event is emitted, XdgPopup.configure() and XdgSurface.configure() will be sent with the updated size and position, as well as a new configure serial.

The client should optionally update the content of the popup, but must acknowledge the new popup configuration for the new position to take effect. See XdgSurface.ack_configure() for details.

Parameters:	token (ArgumentType.Uint) – reposition request token

XdgWmBase¶

class pywayland.protocol.xdg_shell.XdgWmBase¶

Create desktop-style surfaces

The XdgWmBase interface is exposed as a global object enabling clients to turn their wl_surfaces into windows in a desktop environment. It defines the basic functionality needed for clients and the compositor to create windows that can be dragged, resized, maximized, etc, as well as creating transient windows such as popup menus.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy XdgWmBase

Destroy this XdgWmBase object.

Destroying a bound XdgWmBase object while there are surfaces still alive created by this XdgWmBase object instance is illegal and will result in a protocol error.

create_positioner()¶

Request – opcode 1 (attached to Resource instance)

Create a positioner object

Create a positioner object. A positioner object is used to position surfaces relative to some parent surface. See the interface description and XdgSurface.get_popup() for details.

Returns:	`XdgPositioner`

get_xdg_surface(surface)¶

Request – opcode 2 (attached to Resource instance)

Create a shell surface from a surface

This creates an XdgSurface for the given surface. While XdgSurface itself is not a role, the corresponding surface may only be assigned a role extending XdgSurface, such as XdgToplevel or XdgPopup.

This creates an XdgSurface for the given surface. An XdgSurface is used as basis to define a role to a given surface, such as XdgToplevel or XdgPopup. It also manages functionality shared between XdgSurface based surface roles.

See the documentation of XdgSurface for more details about what an XdgSurface is and how it is used.

Parameters:	surface (`WlSurface`) –
Returns:	`XdgSurface`

pong(serial)¶

Request – opcode 3 (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. See XdgWmBase.ping().

Parameters:	serial (ArgumentType.Uint) – serial of the ping event

ping(serial)¶

Event – opcode 0 (attached to Proxy instance)

Check if the client is alive

The ping event asks the client if it’s still alive. Pass the serial specified in the event back to the compositor by sending a “pong” request back with the specified serial. See XdgWmBase.pong().

Compositors can use this to determine if the client is still alive. It’s unspecified what will happen if the client doesn’t respond to the ping request, or in what timeframe. Clients should try to respond in a reasonable amount of time.

A compositor is free to ping in any way it wants, but a client must always respond to any XdgWmBase object it created.

Parameters:	serial (ArgumentType.Uint) – pass this to the pong request

XdgSurface¶

class pywayland.protocol.xdg_shell.XdgSurface¶

Desktop user interface surface base interface

An interface that may be implemented by a WlSurface, for implementations that provide a desktop-style user interface.

It provides a base set of functionality required to construct user interface elements requiring management by the compositor, such as toplevel windows, menus, etc. The types of functionality are split into XdgSurface roles.

Creating an XdgSurface does not set the role for a WlSurface. In order to map an XdgSurface, the client must create a role-specific object using, e.g., get_toplevel, get_popup. The WlSurface for any given XdgSurface can have at most one role, and may not be assigned any role not based on XdgSurface.

A role must be assigned before any other requests are made to the XdgSurface object.

The client must call WlSurface.commit() on the corresponding WlSurface for the XdgSurface state to take effect.

Creating an XdgSurface from a WlSurface which has a buffer attached or committed is a client error, and any attempts by a client to attach or manipulate a buffer prior to the first XdgSurface.configure() call must also be treated as errors.

Mapping an XdgSurface-based role surface is defined as making it possible for the surface to be shown by the compositor. Note that a mapped surface is not guaranteed to be visible once it is mapped.

For an XdgSurface to be mapped by the compositor, the following conditions must be met: (1) the client has assigned an XdgSurface-based role to the surface (2) the client has set and committed the XdgSurface state and the role-dependent state to the surface (3) the client has committed a buffer to the surface

A newly-unmapped surface is considered to have met condition (1) out of the 3 required conditions for mapping a surface if its role surface has not been destroyed.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the XdgSurface

Destroy the XdgSurface object. An XdgSurface must only be destroyed after its role object has been destroyed.

get_toplevel()¶

Request – opcode 1 (attached to Resource instance)

Assign the XdgToplevel surface role

This creates an XdgToplevel object for the given XdgSurface and gives the associated WlSurface the XdgToplevel role.

See the documentation of XdgToplevel for more details about what an XdgToplevel is and how it is used.

Returns:	`XdgToplevel`

get_popup(parent, positioner)¶

Request – opcode 2 (attached to Resource instance)

Assign the XdgPopup surface role

This creates an XdgPopup object for the given XdgSurface and gives the associated WlSurface the XdgPopup role.

If null is passed as a parent, a parent surface must be specified using some other protocol, before committing the initial state.

See the documentation of XdgPopup for more details about what an XdgPopup is and how it is used.

Parameters:	parent (`XdgSurface` or None) – positioner (`XdgPositioner`) –
Returns:	`XdgPopup`

set_window_geometry(x, y, width, height)¶

Request – opcode 3 (attached to Resource instance)

Set the new window geometry

The window geometry of a surface is its “visible bounds” from the user’s perspective. Client-side decorations often have invisible portions like drop-shadows which should be ignored for the purposes of aligning, placing and constraining windows.

The window geometry is double buffered, and will be applied at the time WlSurface.commit() of the corresponding WlSurface is called.

When maintaining a position, the compositor should treat the (x, y) coordinate of the window geometry as the top left corner of the window. A client changing the (x, y) window geometry coordinate should in general not alter the position of the window.

Once the window geometry of the surface is set, it is not possible to unset it, and it will remain the same until set_window_geometry is called again, even if a new subsurface or buffer is attached.

If never set, the value is the full bounds of the surface, including any subsurfaces. This updates dynamically on every commit. This unset is meant for extremely simple clients.

The arguments are given in the surface-local coordinate space of the WlSurface associated with this XdgSurface.

The width and height must be greater than zero. Setting an invalid size will raise an error. When applied, the effective window geometry will be the set window geometry clamped to the bounding rectangle of the combined geometry of the surface of the XdgSurface and the associated subsurfaces.

Parameters:	x (ArgumentType.Int) – y (ArgumentType.Int) – width (ArgumentType.Int) – height (ArgumentType.Int) –

ack_configure(serial)¶

Request – opcode 4 (attached to Resource instance)

Ack a configure event

When a configure event is received, if a client commits the surface in response to the configure event, then the client must make an ack_configure request sometime before the commit request, passing along the serial of the configure event.

For instance, for toplevel surfaces the compositor might use this information to move a surface to the top left only when the client has drawn itself for the maximized or fullscreen state.

If the client receives multiple configure events before it can respond to one, it only has to ack the last configure event.

A client is not required to commit immediately after sending an ack_configure request - it may even ack_configure several times before its next surface commit.

A client may send multiple ack_configure requests before committing, but only the last request sent before a commit indicates which configure event the client really is responding to.

Parameters:	serial (ArgumentType.Uint) – the serial from the configure event

configure(serial)¶

Event – opcode 0 (attached to Proxy instance)

Suggest a surface change

The configure event marks the end of a configure sequence. A configure sequence is a set of one or more events configuring the state of the XdgSurface, including the final XdgSurface.configure() event.

Where applicable, XdgSurface surface roles will during a configure sequence extend this event as a latched state sent as events before the XdgSurface.configure() event. Such events should be considered to make up a set of atomically applied configuration states, where the XdgSurface.configure() commits the accumulated state.

Clients should arrange their surface for the new states, and then send an ack_configure request with the serial sent in this configure event at some point before committing the new surface.

If the client receives multiple configure events before it can respond to one, it is free to discard all but the last event it received.

Parameters:	serial (ArgumentType.Uint) – serial of the configure event

xdg_shell_unstable_v5 Module¶

XdgShell¶

class pywayland.protocol.xdg_shell_unstable_v5.XdgShell¶

Create desktop-style surfaces

XdgShell allows clients to turn a WlSurface into a “real window” which can be dragged, resized, stacked, and moved around by the user. Everything about this interface is suited towards traditional desktop environments.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy XdgShell

Destroy this XdgShell object.

Destroying a bound XdgShell object while there are surfaces still alive created by this XdgShell object instance is illegal and will result in a protocol error.

use_unstable_version(version)¶

Request – opcode 1 (attached to Resource instance)

Enable use of this unstable version

Negotiate the unstable version of the interface. This mechanism is in place to ensure client and server agree on the unstable versions of the protocol that they speak or exit cleanly if they don’t agree. This request will go away once the xdg-shell protocol is stable.

Parameters:	version (ArgumentType.Int) –

get_xdg_surface(surface)¶

Request – opcode 2 (attached to Resource instance)

Create a shell surface from a surface

This creates an XdgSurface for the given surface and gives it the XdgSurface role. A WlSurface can only be given an XdgSurface role once. If get_xdg_surface is called with a WlSurface that already has an active XdgSurface associated with it, or if it had any other role, an error is raised.

See the documentation of XdgSurface for more details about what an XdgSurface is and how it is used.

Parameters:	surface (`WlSurface`) –
Returns:	`XdgSurface`

get_xdg_popup(surface, parent, seat, serial, x, y)¶

Request – opcode 3 (attached to Resource instance)

Create a popup for a surface

This creates an XdgPopup for the given surface and gives it the XdgPopup role. A WlSurface can only be given an XdgPopup role once. If get_xdg_popup is called with a WlSurface that already has an active XdgPopup associated with it, or if it had any other role, an error is raised.

This request must be used in response to some sort of user action like a button press, key press, or touch down event.

See the documentation of XdgPopup for more details about what an XdgPopup is and how it is used.

Parameters:	surface (`WlSurface`) – parent (`WlSurface`) – seat (`WlSeat`) – the `WlSeat` of the user event serial (ArgumentType.Uint) – the serial of the user event x (ArgumentType.Int) – y (ArgumentType.Int) –
Returns:	`XdgPopup`

pong(serial)¶

Request – opcode 4 (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 of the ping event

ping(serial)¶

Event – opcode 0 (attached to Proxy instance)

Check if the client is alive

The ping event asks the client if it’s still alive. Pass the serial specified in the event back to the compositor by sending a “pong” request back with the specified serial.

Compositors can use this to determine if the client is still alive. It’s unspecified what will happen if the client doesn’t respond to the ping request, or in what timeframe. Clients should try to respond in a reasonable amount of time.

A compositor is free to ping in any way it wants, but a client must always respond to any XdgShell object it created.

Parameters:	serial (ArgumentType.Uint) – pass this to the pong request

XdgPopup¶

class pywayland.protocol.xdg_shell_unstable_v5.XdgPopup¶

Short-lived, popup surfaces for menus

A popup surface is a short-lived, temporary surface that can be used to implement menus. It takes an explicit grab on the surface that will be dismissed when the user dismisses the popup. This can be done by the user clicking outside the surface, using the keyboard, or even locking the screen through closing the lid or a timeout.

When the popup is dismissed, a popup_done event will be sent out, and at the same time the surface will be unmapped. The XdgPopup object is now inert and cannot be reactivated, so clients should destroy it. Explicitly destroying the XdgPopup object will also dismiss the popup and unmap the surface.

Clients will receive events for all their surfaces during this grab (which is an “owner-events” grab in X11 parlance). This is done so that users can navigate through submenus and other “nested” popup windows without having to dismiss the topmost popup.

Clients that want to dismiss the popup when another surface of their own is clicked should dismiss the popup using the destroy request.

The parent surface must have either an XdgSurface or XdgPopup role.

Specifying an XdgPopup for the parent means that the popups are nested, with this popup now being the topmost popup. Nested popups must be destroyed in the reverse order they were created in, e.g. the only popup you are allowed to destroy at all times is the topmost one.

If there is an existing popup when creating a new popup, the parent must be the current topmost popup.

A parent surface must be mapped before the new popup is mapped.

When compositors choose to dismiss a popup, they will likely dismiss every nested popup as well. When a compositor dismisses popups, it will follow the same dismissing order as required from the client.

The x and y arguments passed when creating the popup object specify where the top left of the popup should be placed, relative to the local surface coordinates of the parent surface. See XdgShell.get_xdg_popup().

The client must call WlSurface.commit() on the corresponding WlSurface for the XdgPopup state to take effect.

For a surface to be mapped by the compositor the client must have committed both the XdgPopup state and a buffer.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Remove XdgPopup interface

This destroys the popup. Explicitly destroying the XdgPopup object will also dismiss the popup, and unmap the surface.

If this XdgPopup is not the “topmost” popup, a protocol error will be sent.

popup_done()¶

Event – opcode 0 (attached to Proxy instance)

Popup interaction is done

The popup_done event is sent out when a popup is dismissed by the compositor. The client should destroy the XdgPopup object at this point.

XdgSurface¶

class pywayland.protocol.xdg_shell_unstable_v5.XdgSurface¶

A desktop window

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 windows, allowing to set properties like maximized, fullscreen, minimized, and to move and resize them, and associate metadata like title and app id.

The client must call WlSurface.commit() on the corresponding WlSurface for the XdgSurface state to take effect. Prior to committing the new state, it can set up initial configuration, such as maximizing or setting a window geometry.

Even without attaching a buffer the compositor must respond to initial committed configuration, for instance sending a configure event with expected window geometry if the client maximized its surface during initialization.

For a surface to be mapped by the compositor the client must have committed both an XdgSurface state and a buffer.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the XdgSurface

Unmap and destroy the window. The window will be effectively hidden from the user’s point of view, and all state like maximization, fullscreen, and so on, will be lost.

set_parent(parent)¶

Request – opcode 1 (attached to Resource instance)

Set the parent of this surface

Set the “parent” of this surface. This window should be stacked above a parent. The parent surface must be mapped as long as this surface is mapped.

Parent windows should be set on dialogs, toolboxes, or other “auxiliary” surfaces, so that the parent is raised when the dialog is raised.

Parameters:	parent (`XdgSurface` or None) –

set_title(title)¶

Request – opcode 2 (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) –

set_app_id(app_id)¶

Request – opcode 3 (attached to Resource instance)

Set application id

Set an application identifier for the surface.

The app ID identifies the general class of applications to which the surface belongs. The compositor can use this to group multiple surfaces together, or to determine how to launch a new application.

For D-Bus activatable applications, the app ID is used as the D-Bus service name.

The compositor shell will try to group application surfaces together by their app ID. As a best practice, it is suggested to select app ID’s that match the basename of the application’s .desktop file. For example, “org.freedesktop.FooViewer” where the .desktop file is “org.freedesktop.FooViewer.desktop”.

See the desktop-entry specification [0] for more details on application identifiers and how they relate to well-known D-Bus names and .desktop files.

[0] http://standards.freedesktop.org/desktop-entry-spec/

Parameters:	app_id (ArgumentType.String) –

show_window_menu(seat, serial, x, y)¶

Request – opcode 4 (attached to Resource instance)

Show the window menu

Clients implementing client-side decorations might want to show a context menu when right-clicking on the decorations, giving the user a menu that they can use to maximize or minimize the window.

This request asks the compositor to pop up such a window menu at the given position, relative to the local surface coordinates of the parent surface. There are no guarantees as to what menu items the window menu contains.

This request must be used in response to some sort of user action like a button press, key press, or touch down event.

Parameters:	seat (`WlSeat`) – the `WlSeat` of the user event serial (ArgumentType.Uint) – the serial of the user event x (ArgumentType.Int) – the x position to pop up the window menu at y (ArgumentType.Int) – the y position to pop up the window menu at

move(seat, serial)¶

Request – opcode 5 (attached to Resource instance)

Start an interactive move

Start an interactive, user-driven move of the surface.

This request must be used in response to some sort of user action like a button press, key press, or touch down event. The passed serial is used to determine the type of interactive move (touch, pointer, etc).

The server may ignore move requests depending on the state of the surface (e.g. fullscreen or maximized), or if the passed serial is no longer valid.

If triggered, the surface will lose the focus of the device (WlPointer, WlTouch, etc) used for the move. It is up to the compositor to visually indicate that the move is taking place, such as updating a pointer cursor, during the move. There is no guarantee that the device focus will return when the move is completed.

Parameters:	seat (`WlSeat`) – the `WlSeat` of the user event serial (ArgumentType.Uint) – the serial of the user event

resize(seat, serial, edges)¶

Request – opcode 6 (attached to Resource instance)

Start an interactive resize

Start a user-driven, interactive resize of the surface.

This request must be used in response to some sort of user action like a button press, key press, or touch down event. The passed serial is used to determine the type of interactive resize (touch, pointer, etc).

The server may ignore resize requests depending on the state of the surface (e.g. fullscreen or maximized).

If triggered, the client will receive configure events with the “resize” state enum value and the expected sizes. See the “resize” enum value for more details about what is required. The client must also acknowledge configure events using “ack_configure”. After the resize is completed, the client will receive another “configure” event without the resize state.

If triggered, the surface also will lose the focus of the device (WlPointer, WlTouch, etc) used for the resize. It is up to the compositor to visually indicate that the resize is taking place, such as updating a pointer cursor, during the resize. There is no guarantee that the device focus will return when the resize is completed.

The edges parameter specifies how the surface should be resized, and is one of the values of the resize_edge enum. The compositor may use this information to update the surface position for example when dragging the top left corner. The compositor may also use this information to adapt its behavior, e.g. choose an appropriate cursor image.

Parameters:	seat (`WlSeat`) – the `WlSeat` of the user event serial (ArgumentType.Uint) – the serial of the user event edges (ArgumentType.Uint) – which edge or corner is being dragged

ack_configure(serial)¶

Request – opcode 7 (attached to Resource instance)

Ack a configure event

When a configure event is received, if a client commits the surface in response to the configure event, then the client must make an ack_configure request sometime before the commit request, passing along the serial of the configure event.

For instance, the compositor might use this information to move a surface to the top left only when the client has drawn itself for the maximized or fullscreen state.

If the client receives multiple configure events before it can respond to one, it only has to ack the last configure event.

A client is not required to commit immediately after sending an ack_configure request - it may even ack_configure several times before its next surface commit.

The compositor expects that the most recently received ack_configure request at the time of a commit indicates which configure event the client is responding to.

Parameters:	serial (ArgumentType.Uint) – the serial from the configure event

set_window_geometry(x, y, width, height)¶

Request – opcode 8 (attached to Resource instance)

Set the new window geometry

The window geometry of a window is its “visible bounds” from the user’s perspective. Client-side decorations often have invisible portions like drop-shadows which should be ignored for the purposes of aligning, placing and constraining windows.

The window geometry is double buffered, and will be applied at the time WlSurface.commit() of the corresponding WlSurface is called.

Once the window geometry of the surface is set once, it is not possible to unset it, and it will remain the same until set_window_geometry is called again, even if a new subsurface or buffer is attached.

If never set, the value is the full bounds of the surface, including any subsurfaces. This updates dynamically on every commit. This unset mode is meant for extremely simple clients.

If responding to a configure event, the window geometry in here must respect the sizing negotiations specified by the states in the configure event.

The arguments are given in the surface local coordinate space of the WlSurface associated with this XdgSurface.

The width and height must be greater than zero.

Parameters:	x (ArgumentType.Int) – y (ArgumentType.Int) – width (ArgumentType.Int) – height (ArgumentType.Int) –

set_maximized()¶

Request – opcode 9 (attached to Resource instance)

Maximize the window

Maximize the surface.

After requesting that the surface should be maximized, the compositor will respond by emitting a configure event with the “maximized” state and the required window geometry. The client should then update its content, drawing it in a maximized state, i.e. without shadow or other decoration outside of the window geometry. The client must also acknowledge the configure when committing the new content (see ack_configure).

It is up to the compositor to decide how and where to maximize the surface, for example which output and what region of the screen should be used.

If the surface was already maximized, the compositor will still emit a configure event with the “maximized” state.

unset_maximized()¶

Request – opcode 10 (attached to Resource instance)

Unmaximize the window

Unmaximize the surface.

After requesting that the surface should be unmaximized, the compositor will respond by emitting a configure event without the “maximized” state. If available, the compositor will include the window geometry dimensions the window had prior to being maximized in the configure request. The client must then update its content, drawing it in a regular state, i.e. potentially with shadow, etc. The client must also acknowledge the configure when committing the new content (see ack_configure).

It is up to the compositor to position the surface after it was unmaximized; usually the position the surface had before maximizing, if applicable.

If the surface was already not maximized, the compositor will still emit a configure event without the “maximized” state.

set_fullscreen(output)¶

Request – opcode 11 (attached to Resource instance)

Set the window as fullscreen on a monitor

Make the surface fullscreen.

You can specify an output that you would prefer to be fullscreen. If this value is NULL, it’s up to the compositor to choose which display will be used to map this surface.

If the surface doesn’t cover the whole output, the compositor will position the surface in the center of the output and compensate with black borders filling the rest of the output.

Parameters:	output (`WlOutput` or None) –

unset_fullscreen()¶

Request – opcode 12 (attached to Resource instance)

unset_fullscreen

set_minimized()¶

Request – opcode 13 (attached to Resource instance)

Set the window as minimized

Request that the compositor minimize your surface. There is no way to know if the surface is currently minimized, nor is there any way to unset minimization on this surface.

If you are looking to throttle redrawing when minimized, please instead use the WlSurface.frame() event for this, as this will also work with live previews on windows in Alt-Tab, Expose or similar compositor features.

configure(width, height, states, serial)¶

Event – opcode 0 (attached to Proxy instance)

Suggest a surface change

The configure event asks the client to resize its surface or to change its state.

The width and height arguments specify a hint to the window about how its surface should be resized in window geometry coordinates. See set_window_geometry.

If the width or height arguments are zero, it means the client should decide its own window dimension. This may happen when the compositor need to configure the state of the surface but doesn’t have any information about any previous or expected dimension.

The states listed in the event specify how the width/height arguments should be interpreted, and possibly how it should be drawn.

Clients should arrange their surface for the new size and states, and then send a ack_configure request with the serial sent in this configure event at some point before committing the new surface.

If the client receives multiple configure events before it can respond to one, it is free to discard all but the last event it received.

Parameters:	width (ArgumentType.Int) – height (ArgumentType.Int) – states (ArgumentType.Array) – serial (ArgumentType.Uint) –

close()¶

Event – opcode 1 (attached to Proxy instance)

Surface wants to be closed

The close event is sent by the compositor when the user wants the surface to be closed. This should be equivalent to the user clicking the close button in client-side decorations, if your application has any…

This is only a request that the user intends to close your window. The client may choose to ignore this request, or show a dialog to ask the user to save their data…

xdg_shell_unstable_v6 Module¶

ZxdgToplevelV6¶

class pywayland.protocol.xdg_shell_unstable_v6.ZxdgToplevelV6¶

Toplevel surface

This interface defines an XdgSurface role which allows a surface to, among other things, set window-like properties such as maximize, fullscreen, and minimize, set application- specific metadata like title and id, and well as trigger user interactive operations such as interactive resize and move.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the XdgToplevel

Unmap and destroy the window. The window will be effectively hidden from the user’s point of view, and all state like maximization, fullscreen, and so on, will be lost.

set_parent(parent)¶

Request – opcode 1 (attached to Resource instance)

Set the parent of this surface

Set the “parent” of this surface. This window should be stacked above a parent. The parent surface must be mapped as long as this surface is mapped.

Parent windows should be set on dialogs, toolboxes, or other “auxiliary” surfaces, so that the parent is raised when the dialog is raised.

Parameters:	parent (`ZxdgToplevelV6` or None) –

set_title(title)¶

Request – opcode 2 (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) –

set_app_id(app_id)¶

Request – opcode 3 (attached to Resource instance)

Set application id

Set an application identifier for the surface.

The app ID identifies the general class of applications to which the surface belongs. The compositor can use this to group multiple surfaces together, or to determine how to launch a new application.

For D-Bus activatable applications, the app ID is used as the D-Bus service name.

The compositor shell will try to group application surfaces together by their app ID. As a best practice, it is suggested to select app ID’s that match the basename of the application’s .desktop file. For example, “org.freedesktop.FooViewer” where the .desktop file is “org.freedesktop.FooViewer.desktop”.

See the desktop-entry specification [0] for more details on application identifiers and how they relate to well-known D-Bus names and .desktop files.

[0] http://standards.freedesktop.org/desktop-entry-spec/

Parameters:	app_id (ArgumentType.String) –

show_window_menu(seat, serial, x, y)¶

Request – opcode 4 (attached to Resource instance)

Show the window menu

Clients implementing client-side decorations might want to show a context menu when right-clicking on the decorations, giving the user a menu that they can use to maximize or minimize the window.

This request asks the compositor to pop up such a window menu at the given position, relative to the local surface coordinates of the parent surface. There are no guarantees as to what menu items the window menu contains.

This request must be used in response to some sort of user action like a button press, key press, or touch down event.

Parameters:	seat (`WlSeat`) – the `WlSeat` of the user event serial (ArgumentType.Uint) – the serial of the user event x (ArgumentType.Int) – the x position to pop up the window menu at y (ArgumentType.Int) – the y position to pop up the window menu at

move(seat, serial)¶

Request – opcode 5 (attached to Resource instance)

Start an interactive move

Start an interactive, user-driven move of the surface.

This request must be used in response to some sort of user action like a button press, key press, or touch down event. The passed serial is used to determine the type of interactive move (touch, pointer, etc).

The server may ignore move requests depending on the state of the surface (e.g. fullscreen or maximized), or if the passed serial is no longer valid.

If triggered, the surface will lose the focus of the device (WlPointer, WlTouch, etc) used for the move. It is up to the compositor to visually indicate that the move is taking place, such as updating a pointer cursor, during the move. There is no guarantee that the device focus will return when the move is completed.

Parameters:	seat (`WlSeat`) – the `WlSeat` of the user event serial (ArgumentType.Uint) – the serial of the user event

resize(seat, serial, edges)¶

Request – opcode 6 (attached to Resource instance)

Start an interactive resize

Start a user-driven, interactive resize of the surface.

This request must be used in response to some sort of user action like a button press, key press, or touch down event. The passed serial is used to determine the type of interactive resize (touch, pointer, etc).

The server may ignore resize requests depending on the state of the surface (e.g. fullscreen or maximized).

If triggered, the client will receive configure events with the “resize” state enum value and the expected sizes. See the “resize” enum value for more details about what is required. The client must also acknowledge configure events using “ack_configure”. After the resize is completed, the client will receive another “configure” event without the resize state.

If triggered, the surface also will lose the focus of the device (WlPointer, WlTouch, etc) used for the resize. It is up to the compositor to visually indicate that the resize is taking place, such as updating a pointer cursor, during the resize. There is no guarantee that the device focus will return when the resize is completed.

The edges parameter specifies how the surface should be resized, and is one of the values of the resize_edge enum. The compositor may use this information to update the surface position for example when dragging the top left corner. The compositor may also use this information to adapt its behavior, e.g. choose an appropriate cursor image.

Parameters:	seat (`WlSeat`) – the `WlSeat` of the user event serial (ArgumentType.Uint) – the serial of the user event edges (ArgumentType.Uint) – which edge or corner is being dragged

set_max_size(width, height)¶

Request – opcode 7 (attached to Resource instance)

Set the maximum size

Set a maximum size for the window.

The client can specify a maximum size so that the compositor does not try to configure the window beyond this size.

The width and height arguments are in window geometry coordinates. See XdgSurface.set_window_geometry().

Values set in this way are double-buffered. They will get applied on the next commit.

The compositor can use this information to allow or disallow different states like maximize or fullscreen and draw accurate animations.

Similarly, a tiling window manager may use this information to place and resize client windows in a more effective way.

The client should not rely on the compositor to obey the maximum size. The compositor may decide to ignore the values set by the client and request a larger size.

If never set, or a value of zero in the request, means that the client has no expected maximum size in the given dimension. As a result, a client wishing to reset the maximum size to an unspecified state can use zero for width and height in the request.

Requesting a maximum size to be smaller than the minimum size of a surface is illegal and will result in a protocol error.

The width and height must be greater than or equal to zero. Using strictly negative values for width and height will result in a protocol error.

Parameters:	width (ArgumentType.Int) – height (ArgumentType.Int) –

set_min_size(width, height)¶

Request – opcode 8 (attached to Resource instance)

Set the minimum size

Set a minimum size for the window.

The client can specify a minimum size so that the compositor does not try to configure the window below this size.

The width and height arguments are in window geometry coordinates. See XdgSurface.set_window_geometry().

Values set in this way are double-buffered. They will get applied on the next commit.

The compositor can use this information to allow or disallow different states like maximize or fullscreen and draw accurate animations.

Similarly, a tiling window manager may use this information to place and resize client windows in a more effective way.

The client should not rely on the compositor to obey the minimum size. The compositor may decide to ignore the values set by the client and request a smaller size.

If never set, or a value of zero in the request, means that the client has no expected minimum size in the given dimension. As a result, a client wishing to reset the minimum size to an unspecified state can use zero for width and height in the request.

Requesting a minimum size to be larger than the maximum size of a surface is illegal and will result in a protocol error.

The width and height must be greater than or equal to zero. Using strictly negative values for width and height will result in a protocol error.

Parameters:	width (ArgumentType.Int) – height (ArgumentType.Int) –

set_maximized()¶

Request – opcode 9 (attached to Resource instance)

Maximize the window

Maximize the surface.

After requesting that the surface should be maximized, the compositor will respond by emitting a configure event with the “maximized” state and the required window geometry. The client should then update its content, drawing it in a maximized state, i.e. without shadow or other decoration outside of the window geometry. The client must also acknowledge the configure when committing the new content (see ack_configure).

It is up to the compositor to decide how and where to maximize the surface, for example which output and what region of the screen should be used.

If the surface was already maximized, the compositor will still emit a configure event with the “maximized” state.

unset_maximized()¶

Request – opcode 10 (attached to Resource instance)

Unmaximize the window

Unmaximize the surface.

After requesting that the surface should be unmaximized, the compositor will respond by emitting a configure event without the “maximized” state. If available, the compositor will include the window geometry dimensions the window had prior to being maximized in the configure request. The client must then update its content, drawing it in a regular state, i.e. potentially with shadow, etc. The client must also acknowledge the configure when committing the new content (see ack_configure).

It is up to the compositor to position the surface after it was unmaximized; usually the position the surface had before maximizing, if applicable.

If the surface was already not maximized, the compositor will still emit a configure event without the “maximized” state.

set_fullscreen(output)¶

Request – opcode 11 (attached to Resource instance)

Set the window as fullscreen on a monitor

Make the surface fullscreen.

You can specify an output that you would prefer to be fullscreen. If this value is NULL, it’s up to the compositor to choose which display will be used to map this surface.

If the surface doesn’t cover the whole output, the compositor will position the surface in the center of the output and compensate with black borders filling the rest of the output.

Parameters:	output (`WlOutput` or None) –

unset_fullscreen()¶

Request – opcode 12 (attached to Resource instance)

unset_fullscreen

set_minimized()¶

Request – opcode 13 (attached to Resource instance)

Set the window as minimized

Request that the compositor minimize your surface. There is no way to know if the surface is currently minimized, nor is there any way to unset minimization on this surface.

If you are looking to throttle redrawing when minimized, please instead use the WlSurface.frame() event for this, as this will also work with live previews on windows in Alt-Tab, Expose or similar compositor features.

configure(width, height, states)¶

Event – opcode 0 (attached to Proxy instance)

Suggest a surface change

This configure event asks the client to resize its toplevel surface or to change its state. The configured state should not be applied immediately. See XdgSurface.configure() for details.

The width and height arguments specify a hint to the window about how its surface should be resized in window geometry coordinates. See set_window_geometry.

If the width or height arguments are zero, it means the client should decide its own window dimension. This may happen when the compositor needs to configure the state of the surface but doesn’t have any information about any previous or expected dimension.

The states listed in the event specify how the width/height arguments should be interpreted, and possibly how it should be drawn.

Clients must send an ack_configure in response to this event. See XdgSurface.configure() and XdgSurface.ack_configure() for details.

Parameters:	width (ArgumentType.Int) – height (ArgumentType.Int) – states (ArgumentType.Array) –

close()¶

Event – opcode 1 (attached to Proxy instance)

Surface wants to be closed

The close event is sent by the compositor when the user wants the surface to be closed. This should be equivalent to the user clicking the close button in client-side decorations, if your application has any.

This is only a request that the user intends to close the window. The client may choose to ignore this request, or show a dialog to ask the user to save their data, etc.

ZxdgPositionerV6¶

class pywayland.protocol.xdg_shell_unstable_v6.ZxdgPositionerV6¶

Child surface positioner

The XdgPositioner provides a collection of rules for the placement of a child surface relative to a parent surface. Rules can be defined to ensure the child surface remains within the visible area’s borders, and to specify how the child surface changes its position, such as sliding along an axis, or flipping around a rectangle. These positioner-created rules are constrained by the requirement that a child surface must intersect with or be at least partially adjacent to its parent surface.

See the various requests for details about possible rules.

At the time of the request, the compositor makes a copy of the rules specified by the XdgPositioner. Thus, after the request is complete the XdgPositioner object can be destroyed or reused; further changes to the object will have no effect on previous usages.

For an XdgPositioner object to be considered complete, it must have a non-zero size set by set_size, and a non-zero anchor rectangle set by set_anchor_rect. Passing an incomplete XdgPositioner object when positioning a surface raises an error.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the XdgPositioner object

Notify the compositor that the XdgPositioner will no longer be used.

set_size(width, height)¶

Request – opcode 1 (attached to Resource instance)

Set the size of the to-be positioned rectangle

Set the size of the surface that is to be positioned with the positioner object. The size is in surface-local coordinates and corresponds to the window geometry. See XdgSurface.set_window_geometry().

If a zero or negative size is set the invalid_input error is raised.

Parameters:	width (ArgumentType.Int) – width of positioned rectangle height (ArgumentType.Int) – height of positioned rectangle

set_anchor_rect(x, y, width, height)¶

Request – opcode 2 (attached to Resource instance)

Set the anchor rectangle within the parent surface

Specify the anchor rectangle within the parent surface that the child surface will be placed relative to. The rectangle is relative to the window geometry as defined by XdgSurface.set_window_geometry() of the parent surface. The rectangle must be at least 1x1 large.

When the XdgPositioner object is used to position a child surface, the anchor rectangle may not extend outside the window geometry of the positioned child’s parent surface.

If a zero or negative size is set the invalid_input error is raised.

Parameters:	x (ArgumentType.Int) – x position of anchor rectangle y (ArgumentType.Int) – y position of anchor rectangle width (ArgumentType.Int) – width of anchor rectangle height (ArgumentType.Int) – height of anchor rectangle

set_anchor(anchor)¶

Request – opcode 3 (attached to Resource instance)

Set anchor rectangle anchor edges

Defines a set of edges for the anchor rectangle. These are used to derive an anchor point that the child surface will be positioned relative to. If two orthogonal edges are specified (e.g. ‘top’ and ‘left’), then the anchor point will be the intersection of the edges (e.g. the top left position of the rectangle); otherwise, the derived anchor point will be centered on the specified edge, or in the center of the anchor rectangle if no edge is specified.

If two parallel anchor edges are specified (e.g. ‘left’ and ‘right’), the invalid_input error is raised.

Parameters:	anchor (ArgumentType.Uint) – bit mask of anchor edges

set_gravity(gravity)¶

Request – opcode 4 (attached to Resource instance)

Set child surface gravity

Defines in what direction a surface should be positioned, relative to the anchor point of the parent surface. If two orthogonal gravities are specified (e.g. ‘bottom’ and ‘right’), then the child surface will be placed in the specified direction; otherwise, the child surface will be centered over the anchor point on any axis that had no gravity specified.

If two parallel gravities are specified (e.g. ‘left’ and ‘right’), the invalid_input error is raised.

Parameters:	gravity (ArgumentType.Uint) – bit mask of gravity directions

set_constraint_adjustment(constraint_adjustment)¶

Request – opcode 5 (attached to Resource instance)

Set the adjustment to be done when constrained

Specify how the window should be positioned if the originally intended position caused the surface to be constrained, meaning at least partially outside positioning boundaries set by the compositor. The adjustment is set by constructing a bitmask describing the adjustment to be made when the surface is constrained on that axis.

If no bit for one axis is set, the compositor will assume that the child surface should not change its position on that axis when constrained.

If more than one bit for one axis is set, the order of how adjustments are applied is specified in the corresponding adjustment descriptions.

The default adjustment is none.

Parameters:	constraint_adjustment (ArgumentType.Uint) – bit mask of constraint adjustments

set_offset(x, y)¶

Request – opcode 6 (attached to Resource instance)

Set surface position offset

Specify the surface position offset relative to the position of the anchor on the anchor rectangle and the anchor on the surface. For example if the anchor of the anchor rectangle is at (x, y), the surface has the gravity bottom|right, and the offset is (ox, oy), the calculated surface position will be (x + ox, y + oy). The offset position of the surface is the one used for constraint testing. See set_constraint_adjustment.

An example use case is placing a popup menu on top of a user interface element, while aligning the user interface element of the parent surface with some user interface element placed somewhere in the popup surface.

Parameters:	x (ArgumentType.Int) – surface position x offset y (ArgumentType.Int) – surface position y offset

ZxdgSurfaceV6¶

class pywayland.protocol.xdg_shell_unstable_v6.ZxdgSurfaceV6¶

Desktop user interface surface base interface

An interface that may be implemented by a WlSurface, for implementations that provide a desktop-style user interface.

It provides a base set of functionality required to construct user interface elements requiring management by the compositor, such as toplevel windows, menus, etc. The types of functionality are split into XdgSurface roles.

Creating an XdgSurface does not set the role for a WlSurface. In order to map an XdgSurface, the client must create a role-specific object using, e.g., get_toplevel, get_popup. The WlSurface for any given XdgSurface can have at most one role, and may not be assigned any role not based on XdgSurface.

A role must be assigned before any other requests are made to the XdgSurface object.

The client must call WlSurface.commit() on the corresponding WlSurface for the XdgSurface state to take effect.

Creating an XdgSurface from a WlSurface which has a buffer attached or committed is a client error, and any attempts by a client to attach or manipulate a buffer prior to the first XdgSurface.configure() call must also be treated as errors.

For a surface to be mapped by the compositor, the following conditions must be met: (1) the client has assigned a XdgSurface based role to the surface, (2) the client has set and committed the XdgSurface state and the role dependent state to the surface and (3) the client has committed a buffer to the surface.

destroy()¶

Request – opcode 0 (attached to Resource instance)

Destroy the XdgSurface

Destroy the XdgSurface object. An XdgSurface must only be destroyed after its role object has been destroyed.

get_toplevel()¶

Request – opcode 1 (attached to Resource instance)

Assign the XdgToplevel surface role

This creates an XdgToplevel object for the given XdgSurface and gives the associated WlSurface the XdgToplevel role.

See the documentation of XdgToplevel for more details about what an XdgToplevel is and how it is used.

Returns:	`ZxdgToplevelV6`

get_popup(parent, positioner)¶

Request – opcode 2 (attached to Resource instance)

Assign the XdgPopup surface role

This creates an XdgPopup object for the given XdgSurface and gives the associated WlSurface the XdgPopup role.

See the documentation of XdgPopup for more details about what an XdgPopup is and how it is used.

Parameters:	parent (`ZxdgSurfaceV6`) – positioner (`ZxdgPositionerV6`) –
Returns:	`ZxdgPopupV6`

set_window_geometry(x, y, width, height)¶

Request – opcode 3 (attached to Resource instance)

Set the new window geometry

The window geometry of a surface is its “visible bounds” from the user’s perspective. Client-side decorations often have invisible portions like drop-shadows which should be ignored for the purposes of aligning, placing and constraining windows.

The window geometry is double buffered, and will be applied at the time WlSurface.commit() of the corresponding WlSurface is called.

Once the window geometry of the surface is set, it is not possible to unset it, and it will remain the same until set_window_geometry is called again, even if a new subsurface or buffer is attached.

If never set, the value is the full bounds of the surface, including any subsurfaces. This updates dynamically on every commit. This unset is meant for extremely simple clients.

The arguments are given in the surface-local coordinate space of the WlSurface associated with this XdgSurface.

The width and height must be greater than zero. Setting an invalid size will raise an error. When applied, the effective window geometry will be the set window geometry clamped to the bounding rectangle of the combined geometry of the surface of the XdgSurface and the associated subsurfaces.

Parameters:	x (ArgumentType.Int) – y (ArgumentType.Int) – width (ArgumentType.Int) – height (ArgumentType.Int) –

ack_configure(serial)¶

Request – opcode 4 (attached to Resource instance)

Ack a configure event

When a configure event is received, if a client commits the surface in response to the configure event, then the client must make an ack_configure request sometime before the commit request, passing along the serial of the configure event.

For instance, for toplevel surfaces the compositor might use this information to move a surface to the top left only when the client has drawn itself for the maximized or fullscreen state.

If the client receives multiple configure events before it can respond to one, it only has to ack the last configure event.

A client is not required to commit immediately after sending an ack_configure request - it may even ack_configure several times before its next surface commit.

A client may send multiple ack_configure requests before committing, but only the last request sent before a commit indicates which configure event the client really is responding to.

Parameters:	serial (ArgumentType.Uint) – the serial from the configure event

configure(serial)¶

Event – opcode 0 (attached to Proxy instance)

Suggest a surface change

The configure event marks the end of a configure sequence. A configure sequence is a set of one or more events configuring the state of the XdgSurface, including the final XdgSurface.configure() event.

Where applicable, XdgSurface surface roles will during a configure sequence extend this event as a latched state sent as events before the XdgSurface.configure() event. Such events should be considered to make up a set of atomically applied configuration states, where the XdgSurface.configure() commits the accumulated state.

Clients should arrange their surface for the new states, and then send an ack_configure request with the serial sent in this configure event at some point before committing the new surface.

If the client receives multiple configure events before it can respond to one, it is free to discard all but the last event it received.

Parameters:	serial (ArgumentType.Uint) – serial of the configure event

ZxdgPopupV6¶

class pywayland.protocol.xdg_shell_unstable_v6.ZxdgPopupV6¶

Short-lived, popup surfaces for menus

A popup surface is a short-lived, temporary surface. It can be used to implement for example menus, popovers, tooltips and other similar user interface concepts.

A popup can be made to take an explicit grab. See XdgPopup.grab() for details.

When the popup is dismissed, a popup_done event will be sent out, and at the same time the surface will be unmapped. See the XdgPopup.popup_done() event for details.

Explicitly destroying the XdgPopup object will also dismiss the popup and unmap the surface. Clients that want to dismiss the popup when another surface of their own is clicked should dismiss the popup using the destroy request.

The parent surface must have either the XdgToplevel or XdgPopup surface role.

A newly created XdgPopup will be stacked on top of all previously created XdgPopup surfaces associated with the same XdgToplevel.

The parent of an XdgPopup must be mapped (see the XdgSurface description) before the XdgPopup itself.

The x and y arguments passed when creating the popup object specify where the top left of the popup should be placed, relative to the local surface coordinates of the parent surface. See XdgSurface.get_popup(). An XdgPopup must intersect with or be at least partially adjacent to its parent surface.