Basics

This page provides a more detailed review of the Wayland tablet protocol and is intended for use by compositor and toolkit developers. Application developers should not use the Wayland tablet protocol directly, but instead rely on support provided by their toolkit.

This documentation specifically regards version 2 of the tablet protocol. It covers the objects named (e.g. "zwp_tablet_*v2" )

Introduction

Features

The Wayland tablet protocol (also known as wp_tablet or zwp_tablet) provides a channel for sending graphics tablet events from the compositor to applications. It is designed to be compatible with a wide variety of devices and use-cases: from handwriting and sketching with an entry-level digitizer, to using programmable buttons and tool-specific configurations across opaque and display tablets. Support for these more complex scenarios complicates the protocol somewhat, resulting in a number of departures from how mouse and touchscreen input is reported.

	wl_pointer	wl_touch	wp_tablet
Mode	Relative	Absolute	Absolute
Interaction	Indirect	Direct	Both
Architecture	Frame-based	Frame-based	Frame-based
Pointing Devices	One	One	Multiple
Pointing Contexts	One	Multiple (per-finger)	Multiple (per-tool)
Pointing Tools	Mouse Touchpad	Touchscreen	Pen / Eraser Airbrush Puck
Axes	Position	Position Shape Orientation	Position Pressure Distance Tilt Rotation "Slider"
Additional Features	-	-	"Pad" controls

The most notable difference between this protocol and wl_pointer / wl_touch is its choice to expose input devices through the protocol. This allows applications to provide feedback about connected devices or offer tablet-specific behavior (e.g. hiding tool cursors for display tablets). Along a similar vein, each tool is tracked independently allowing applications to respond to events from multiple tools simultaneously (e.g. for electronic whiteboarding).

Another interesting feature of this protocol is its support for so-called "pad" controls. These are buttons, touch rings, and other user-programmable inputs which provide instant access to program shortcuts and settings. Many tablets include some number of pad controls on the tablet surface; dedicated pad devices can also be purchased. Applications are encouraged to use the set_feedback requests to inform the compositor of what each control is currently programmed to do, so that a compositor may provide on-screen feedback or help displays.

Compatibility

Tablet support in Wayland environments is not universal, but many projects have taken on the task. The two most popular toolkits and desktops for Linux have added Wayland tablet support and the xwayland translation layer ensures legacy X11-based applications are able to continue working in compatible environments. The following table highlights some of the projects known to support the Wayland tablet protocol.

Project	Type	Version	Notes
GTK+ 3	UI Toolkit	>= 3.22	Application developers should refer to the GTK+ Overview and not use the Wayland protocol directly.
Qt 5	UI Toolkit	>= 5.15	Application developers should refer to the Qt Overview and not use the Wayland protocol directly.
Mutter	Compositor	>= 3.22	Compositor for GNOME desktop.
Sway	Compositor	>= 1.3	-
KWin	Compositor	>= 5.19	Compositor for KDE Plasma desktop.
wl-roots	Compositor Library	>= 0.8.1	-
xwayland	Translation Layer	>= 1.20.0	Translates Wayland events on behalf of X11 clients.

This list is not complete, but due to the more fragmented nature of the Wayland ecosystem (compared to what Linux experienced with X11), encountering other incompatible environments is likely. Also, it should be noted that even when using toolkits and compositors which are nominally compatible, the existence of implementation bugs may impact usability or performance. It is always recommended to base development on the most current releases to minimize these issues.

Understanding the Protocol

The Wayland tablet protocol describes the various devices, tools, and controls which a tablet peripheral may add to a system. Its interfaces form a tree of related objects, starting at a single global "tablet manager":

• Tablet Manager
  • Tablet Seat
    • Tablet
    • Tool
    • Pad
      • Pad Group
        • Ring
        • Strip

Drilling down from the tablet manager, you next encounter the "tablet seat": the tablet protocol's analog to the standard protocol's wl_seat objects. From here you get access to the various tablet-related hardware that is actually associated with the seat. A bare-bones compositor or toolkit implementation of the protocol might only consider the "tablet" and "tool" branches, as these are the minimum required to get pen input working. For a full experience, however, compositors and toolkits should also strive to implement the "pad" branch as well. The tablet pad and its controls are significant to many users, offering immediate access to numerous shortcuts and features.

The tablet protocol was designed to be easy to wire up with the libinput library that many compositors are already using for keyboard, mouse, and touchscreen input. In addition, compositor and toolkit developers may want to explore the libwacom library as well, since it may contain additional information that can be useful for writing concrete implementations.

Tablet Manager

At the root of the protocol is the zwp_tablet_manager_v2 interface. This interface is described as "a proxy object" which "provides access to the graphics tablets available on this system." This object is a singleton created by the compositor and registered as a global object in the protocol registry. Clients should bind to the object, which acts as a doorway to the rest of the protocol. Its presence (or absence) may be used as an indication of whether the tablet protocol is supported by the compositor.

The tablet manager's sole purpose is to act as a stable interface into the rest of the tablet protocol. At the moment, it only defines one item of consequence: the get_tablet_seat request. If other top-level events or requests are required in the future, they would be added to this interface. This minimizes the number of globals that need to be maintained in the registry.

Tablet Seat

The zwp_tablet_seat_v2 interface is described as a "controller object" which "provides access to all graphics tablets in [the requested] seat." Where the tablet manager interface maintains global state, the tablet seat maintains seat-specific state. Tablet seats are analogous in function to wl_seat objects in the core protocol, grouping devices under the logical control of a single user. Compositors and clients are expected to manage tablet devices and seats in parallel with core devices and seats. Keyboard focus, for example, should follow tablet tools similar to how focus is handled for pointer and touch input. Clients should request a tablet seat object for each wl_seat they track to ensure all potential tablet input sources are known about.

The tablet seat defines three events of interest: tablet_added, tool_added, and pad_added. These events are fired after the client binds to a seat and provide information about all currently-connected devices. They are also sent any time a new tablet / tool / pad is connected to the seat. Removal is signaled with events sent by the objects themselves.

Tablet

The zwp_tablet_v2 interface provides access to hardware information about each tablet connected to the system. As described, it "represents one graphics tablet device" and its "static characteristics, e.g. device name and vid/pid." Input events are not sent from this interface; rather, events are sent from the tool, pad, etc. interfaces, which are themselves associated with a tablet. The compositor should create new tablet objects any time libinput informs it that one has connected. Clients may use the information provided by this interface to look up additional device properties (e.g. via libwacom) or leave the objects alone if they have no interest in tablet-specific behaviors.

While it is uncommon to find multiple tablets connected to a single seat, it is not unheard of. Many tablet PCs include pen sensors built into their displays, and users may find themselves connecting an external tablet for improved performance (especially in the case of docking with an external display tablet). Artists have also been known to have both a display and opaque tablet connected, switching between the two to work more effectively with dual-head setups.

Tablet Tool

The zwp_tablet_tool_v2 interface is the heart of the tablet protocol. It is described as "represent[ing] a physical tool that has been, or currently is in use with a tablet in this seat." The compositor allocates one tool object for each physical tool, using serial number information (when available) as a guide. These tool objects are re-used when possible; not only when a tool leaves and re-enters proximity on one tablet, but even when the tool re-enters proximity on a completely different tablet. This re-use makes it possible for applications to assign tool-specific preferences that follow the tool wherever it goes (e.g treating one pen as "red" and a second pen as "blue" regardless of where it is used).

When a new tool is added, the compositor first sends a burst of events that provides tool information to the client. This burst includes tool type, serial number, and capability data. Afterwards, the compositor is free to send frame-delimited updates to the tool state. These events mirror the data available from libinput – proximity, motion, pressure, etc. Clients should use these updates to refresh their own view of the tool state and commit the changes whenever a frame event is received.

Many low-end tablets do not report tool serial number information, making it impossible for the compositor to track them across tablets. The safest and easiest option may be to create a tool object for each such tablet. A compositor could also create just a single generic tool object and ensure that it is only used with tablets that have the same set of capabilities.

In the common case, most users will have one or two tools that need to be tracked. Basic tablets will have only a stylus, while mid-range and better devices will often have tools that also have an eraser end. The eraser is often tracked independently from the stylus tip, which leads to its presence as a distinct advertised tool type. Other tool types may be purchased by individuals with specific needs. The "mouse" type in particular is a tool which is physically similar to a typical mouse, although it natively uses absolute coordinates like other tools. Compositors are free to redirect input events from such "mouse" tools to the wl_pointer interface (and similar for toolkits), but should be aware that these tools need special care (e.g. translating motion to relative deltas, and programmatically suppressing motion when the "mouse" is picked up for repositioning).

Note that it is possible for multiple tools to be in proximity at the same time – both on different surfaces and on the same surface. This may occur if a user has multiple tablets plugged in, or if a single tablet supports multi-tool operation (e.g. an electronic whiteboard). Compositors should send updates for all tools that it is aware of, ensuring that multi-pen capable applications work properly. Clients should handle events from multiple tools as gracefully as possible. Toolkits should take care to ensure that the event stream sent to clients is sane. If the toolkit API permits multiple tools to be in proximity simultaneously, events may be forwarded from the compositor as-is. If the toolkit API only supports a single tool in proximity at a time, the toolkit may opt to ignore events from subsequent tools.

Tablet Pad

The zwp_tablet_pad_v2 interface is the parent object for any controls which are present on the tablet's surface. It is primarily a container for "group" objects which partition the controls into sets of logically-related controls. It also provides much of the interface necessary for interacting with any pad buttons.

When a pad is first initialized, the compositor will send a burst of events describing it. This will include one or more group events, along with an event specifying the total number of buttons available on the tablet. The compositor should consult libwacom for information on each. After this burst of events, the compositor should send enter and leave events that follow focus, as well as button events when the user presses a non-reserved button.

The compositor is free to define its own focus-following rules for sending pad enter and leave events. Programs have traditionally expected the pad to send keyboard shortcuts and mouse button/wheel events, so obvious choices are to follow keyboard focus or follow the focus of an in-prox tool.

Button events inform the client whenever a particular button has been pressed: they have no predetermined meaning and are expected to be processed by the client according to its (perhaps user-defined) configuration. The compositor is free to reserve buttons for its own use by not mentioning them in any group and then acting on the button event itself when it is received. As with clients, the compositor is free to impose its own meaning onto the buttons it reserves for itself. A compositor might reserve a button for mode-switch events, allow the user to configure some buttons to act as global keyboard shortcuts, have a button change which screen a tablet is mapped to, or trigger screen recording. Note that button states are represented with an enum rather than a simple pressed / released flag. This is for future expansion and use by pad buttons which could e.g. sense that the user is merely touching (rather than pressing) a button.

The pad interface provides a special set_feedback request for buttons, similar to the ring and strip interfaces. See the "Rings and Strips" section below for more details.

Groups

The zwp_tablet_pad_group_v2 interface describes the functional layout of a pad. The controls on the surface of a pad are logically organized into groups, often based on a physical proximity to each other. A pad will always have at least one group, with each group consisting of some set of buttons, rings, and strips. Groups are also specified to have some number of "modes"; if multiple modes are available, the user may switch between them to access alternate control functions.

When a group is first initialized, the compositor will send a burst of events describing all of its associated controls. This burst includes an array of button indices which are associated with the group, along with notifications for ring and strip objects that may be present. Afterwards, only mode_switch events will be sent from this interface.

Compositors are free to implement their own policies for mode switching. Some tablets have dedicated mode-switch buttons and indicators: compositors may request information about these from libwacom and then reserve the buttons for its own use. Compositors may also decide to offer a mode switching feature purely in software for tablets without any dedicated hardware; they should again reserve any associated buttons and make use of on-screen-displays to provide mode-switch feedback to the user.

Clients are expected to respond to mode switch events by swapping out any configuration they have for buttons, rings, and / or strips as the client sees fit. For example, a client may decide that receiving a mode switch event only affects how it responds to touch ring input. In one mode it may treat the ring as a zoom control, and in another mode it may treat it as a timeline scrub control. Another client may decide to let the mode switch offer the user multiple banks of programmable button actions, vastly extending the number of accessible shortcuts. Whenever a mode switch event occurs, clients should be sure to send set_feedback requests on the buttons, rings, and strips (see the "Rings and Strips" section below) to ensure the compositor can communicate their new function to the user.

Rings and Strips

The zwp_tablet_pad_ring_v2 and zwp_tablet_pad_strip_v2 interfaces embody any touch rings or touch strips found on the device. They are created by the pad interface and associated with a specific group. Rings and strips are analog controls which allow a user to make smooth adjustments in a client program. Both controls report absolute positioning information, which clients may either use as-is (e.g. the reported touch ring angle could set a brush angle) or convert to relative changes (e.g. clockwise motion around a touch ring could increase brush size).

Rings and strips have an optional source event which can be used to provide additional information about the type of tool which is interacting with the control. This will typically be a finger (the controls on all known tablets only respond to touch) but the option is given to not send a source if not known.

Rings and strips (and buttons) have a set_feedback request which clients may use to communicate the action which will be performed when a control is used. The compositor may use this information to provide on-screen help overlays that graphically show what each control is programmed to do. Compositors could also use this information in combination with touch-sensitive buttons to provide the user with a real-time description of whatever control they are touching. Mode switch events are expected to invalidate the current feedback information, so clients should be prepared to send a fresh set of set_feedback requests in response describing the updated use of each control.