xdg_toplevel_icon_v1¤
A toplevel window icon
This interface defines a toplevel icon. An icon can have a name, and multiple buffers. In order to be applied, the icon must have either a name, or at least one buffer assigned. Applying an empty icon (with no buffer or name) to a toplevel should reset its icon to the default icon.
It is up to compositor policy whether to prefer using a buffer or loading an icon via its name. See 'set_name' and 'add_buffer' for details.
Methods:
-
destroy–Destroy the icon object
-
set_name–Set an icon name
-
add_buffer–Add icon data from a pixel buffer
-
invalid_buffer–The provided buffer does not satisfy requirements -
immutable–The icon has already been assigned to a toplevel and must not be changed -
no_buffer–The provided buffer has been destroyed before the toplevel icon
destroy() -> None
Destroy the icon object
Destroys the 'xdg_toplevel_icon_v1' object. The icon must still remain set on every toplevel it was assigned to, until the toplevel icon is reset explicitly.
set_name(icon_name: str) -> None
Set an icon name
This request assigns an icon name to this icon. Any previously set name is overridden.
The compositor must resolve 'icon_name' according to the lookup rules described in the XDG icon theme specification1 using the environment's current icon theme.
If the compositor does not support icon names or cannot resolve 'icon_name' according to the XDG icon theme specification it must fall back to using pixel buffer data instead.
If this request is made after the icon has been assigned to a toplevel via 'set_icon', a 'immutable' error must be raised.
Add icon data from a pixel buffer
This request adds pixel data supplied as wl_buffer to the icon.
The client should add pixel data for all icon sizes and scales that it can provide, or which are explicitly requested by the compositor via 'icon_size' events on xdg_toplevel_icon_manager_v1.
The wl_buffer supplying pixel data as 'buffer' must be backed by wl_shm and must be a square (width and height being equal). If any of these buffer requirements are not fulfilled, a 'invalid_buffer' error must be raised.
If this icon instance already has a buffer of the same size and scale from a previous 'add_buffer' request, data from the last request overrides the preexisting pixel data.
The wl_buffer must be kept alive for as long as the xdg_toplevel_icon it is associated with is not destroyed, otherwise a 'no_buffer' error is raised. The buffer contents must not be modified after it was assigned to the icon. As a result, the region of the wl_shm_pool's backing storage used for the wl_buffer must not be modified after this request is sent. The wl_buffer.release event is unused.
If this request is made after the icon has been assigned to a toplevel via 'set_icon', a 'immutable' error must be raised.
Parameters: