Wayland role
also: surface role, window role
A Wayland role is a property that identifies the function or window type of a surface in the Wayland display server, such as whether it represents a top-level application window, a popup, or a tooltip.
In Wayland, a role is an abstract identifier assigned to a surface that defines its purpose and behavior within the compositor. Unlike X11's rigid window hierarchy, Wayland uses roles to allow compositors greater flexibility in how they manage and render different surface types.
Common roles include xdg_toplevel (main application window), xdg_popup (dropdown menus or tooltips), and xdg_positioner (for positioning logic). The role is typically assigned through the XDG Shell protocol when a client creates a surface, and it cannot be changed once set.
For example, when a text editor creates its main window, it assigns the xdg_toplevel role. When a context menu appears, the same editor creates a new surface with the xdg_popup role, signaling to the compositor that this surface should be treated as a temporary overlay tied to the editor window.