Module kazari::wl::protocols::common

Wayland Protocol definitions.

Modules

wl_buffer	A buffer provides the content for a wl_surface. buffers are created through factory interfaces such as wl_drm, wl_shm or similar. it has a width and a height and can be attached to a wl_surface, but the mechanism by which a client provides and updates the contents is defined by the buffer factory interface.
wl_callback	Clients can handle the ‘done’ event to get notified when the related request is done.
wl_compositor	A compositor. this object is a singleton global. the compositor is in charge of combining the contents of multiple surfaces into one displayable output.
wl_data_device	There is one wl_data_device per seat which can be obtained from the global wl_data_device_manager singleton. a wl_data_device provides access to inter- client data transfer mechanisms such as copy-and-paste and drag-and-drop.
wl_data_device_manager	The wl_data_device_manager 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 wl_seat and this interface lets a client get a wl_data_device corresponding to a wl_seat. depending on the version bound, the objects created from the bound wl_data_device_manager object will have different requirements for functioning properly. see wl_data_source.set_actions, wl_data_offer.accept and wl_data_offer.finish for details.
wl_data_offer	A wl_data_offer 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.
wl_data_source	The wl_data_source object is the source side of a wl_data_offer. 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.
wl_display	The core global object. this is a special singleton object. it is used for internal wayland protocol features.
wl_keyboard	The wl_keyboard interface represents one or more keyboards associated with a seat.
wl_output	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.
wl_pointer	The wl_pointer interface represents one or more input devices, such as mice, which control the pointer location and pointer_focus of a seat. the wl_pointer 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.
wl_region	A region object describes an area. region objects are used to describe the opaque and input regions of a surface.
wl_registry	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 wl_display.sync request immediately after calling wl_display.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.
wl_seat	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.
wl_shell	This interface is implemented by servers that provide desktop-style user interfaces. it allows clients to associate a wl_shell_surface with a basic surface. note! this protocol is deprecated and not intended for production use. for desktop-style user interfaces, use xdg_shell.
wl_shell_surface	An interface that may be implemented by a wl_surface, 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 wl_surface is destroyed. on the client side, wl_shell_surface_destroy() must be called before destroying the wl_surface object.
wl_shm	A singleton global object that provides support for shared memory. clients can create wl_shm_pool objects using the create_pool request. at connection setup time, the wl_shm object emits one or more format events to inform clients about the valid pixel formats that can be used for buffers.
wl_shm_pool	The wl_shm_pool object encapsulates a piece of memory shared between the compositor and client. through the wl_shm_pool object, the client can allocate shared memory wl_buffer 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.
wl_subcompositor	The global interface exposing sub-surface compositing capabilities. a wl_surface, 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 wl_surface 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 wl_surface objects. this should allow the compositor to pass yuv video buffer processing to dedicated overlay hardware when possible.
wl_subsurface	An additional interface to a wl_surface 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 wl_buffer 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 wl_buffer is applied. these rules apply recursively through the tree of surfaces. the behaviour of a wl_surface.commit request on a sub-surface depends on the sub-surface’s mode. the possible modes are synchronized and desynchronized, see methods wl_subsurface.set_sync and wl_subsurface.set_desync. synchronized mode caches the wl_surface state to be applied when the parent’s state gets applied, and desynchronized mode applies the pending wl_surface state directly. a sub-surface is initially in the synchronized mode. sub-surfaces also have another kind of state, which is managed by wl_subsurface requests, as opposed to wl_surface requests. this state includes the sub-surface position relative to the parent surface (wl_subsurface.set_position), and the stacking order of the parent and its sub- surfaces (wl_subsurface.place_above and .place_below). this state is applied when the parent surface’s wl_surface 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 wl_surface associated with the wl_subsurface is destroyed, the wl_subsurface 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 wl_buffer, update parent, and then destroy the sub-surface. if the parent wl_surface object is destroyed, the sub-surface is unmapped.
wl_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 wl_surface. examples of roles are a cursor for a pointer (as set by wl_pointer.set_cursor), a drag icon (wl_data_device.start_drag), a sub-surface (wl_subcompositor.get_subsurface), and a window as defined by a shell protocol (e.g. wl_shell.get_shell_surface). a surface can have only one role at a time. initially a wl_surface does not have a role. once a wl_surface is given a role, it is set permanently for the whole lifetime of the wl_surface 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 wl_pointer.set_cursor. the request should explicitly mention that this request gives a role to a wl_surface. often, this request also creates a new protocol object that represents the role and adds additional functionality to wl_surface. when a client wants to destroy a wl_surface, they must destroy this ‘role object’ before the wl_surface. destroying the role object does not remove the role from the wl_surface, but it may stop the wl_surface from “playing the role”. for instance, if a wl_subsurface object is destroyed, the wl_surface it was created for will be unmapped and forget its position and z-order. it is allowed to create a wl_subsurface for the same wl_surface again, but it is not allowed to use the wl_surface as a cursor (cursor is a different role than sub-surface, and role switching is not allowed).
wl_touch	The wl_touch 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.
xdg_popup	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 xdg_popup.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 xdg_popup.popup_done event for details. explicitly destroying the xdg_popup 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 xdg_popup will be stacked on top of all previously created xdg_popup surfaces associated with the same xdg_toplevel. the parent of an xdg_popup must be mapped (see the xdg_surface description) before the xdg_popup itself. the client must call wl_surface.commit on the corresponding wl_surface for the xdg_popup state to take effect.
xdg_positioner	The xdg_positioner 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 xdg_positioner. thus, after the request is complete the xdg_positioner object can be destroyed or reused; further changes to the object will have no effect on previous usages. for an xdg_positioner 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 xdg_positioner object when positioning a surface raises an error.
xdg_surface	An interface that may be implemented by a wl_surface, 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 xdg_surface roles. creating an xdg_surface does not set the role for a wl_surface. in order to map an xdg_surface, the client must create a role- specific object using, e.g., get_toplevel, get_popup. the wl_surface for any given xdg_surface can have at most one role, and may not be assigned any role not based on xdg_surface. a role must be assigned before any other requests are made to the xdg_surface object. the client must call wl_surface.commit on the corresponding wl_surface for the xdg_surface state to take effect. creating an xdg_surface from a wl_surface 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_surface.configure call must also be treated as errors. after creating a role-specific object and setting it up, the client must perform an initial commit without any buffer attached. the compositor will reply with an xdg_surface.configure event. the client must acknowledge it and is then allowed to attach a buffer to map the surface. mapping an xdg_surface-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 xdg_surface to be mapped by the compositor, the following conditions must be met: (1) the client has assigned an xdg_surface-based role to the surface (2) the client has set and committed the xdg_surface 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.
xdg_toplevel	This interface defines an xdg_surface 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 xdg_toplevel 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 xdg_toplevel surface when it is unmapped. the xdg_toplevel returns to the state it had right after xdg_surface.get_toplevel. the client can re-map the toplevel by perfoming a commit without any buffer attached, waiting for a configure event and handling it as usual (see xdg_surface description). attaching a null buffer to a toplevel unmaps the surface.
xdg_wm_base	The xdg_wm_base 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.

Enums

EventSet
RequestSet