ext_workspace_foreign_toplevel_v1
This protocol serves as an intermediary between ext_workspace_v1 protocol and ext_foreign_toplevel_list_v1 protocol to manage toplevels in workspaces.
Warning! The protocol described in this file is currently in the testing phase. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes can only be done by creating a new major version of the extension.
The ext_workspace_foreign_toplevel_manager_v1 interface defines a base request for creating ext_workspace_foreign_toplevel_handle_v1 objects.
get_workspace_toplevel_handle(id: new_id<ext_workspace_foreign_toplevel_handle_v1>, toplevel_handle: object<ext_foreign_toplevel_handle_v1>, workspace_manager: object<ext_workspace_manager_v1>)
Argument | Type | Description |
|---|---|---|
| id | new_id<ext_workspace_foreign_toplevel_handle_v1> | |
| toplevel_handle | object<ext_foreign_toplevel_handle_v1> | |
| workspace_manager | object<ext_workspace_manager_v1> |
Request a toplevel handle for workspace-related operations on the given ext_foreign_toplevel_handle_v1. The workspace_manager argument specifies the source of workspaces objects used in events and requests on the returned handle.
destroy()
Destroys the ext_workspace_foreign_toplevel_manager_v1 object.
A ext_workspace_foreign_toplevel_handle_v1 object represents a handle to associate a toplevel with workspaces.
This object extends the ext_foreign_toplevel_handle_v1 interface and uses the ext_foreign_toplevel_handle_v1.done event to atomically apply pending state.
assign_workspace(workspace: object<ext_workspace_handle_v1>)
Argument | Type | Description |
|---|---|---|
| workspace | object<ext_workspace_handle_v1> |
Request that the toplevel associated with this handle is assigned to the given workspace. This request is double-buffered and applied on the next ext_workspace_foreign_toplevel_handle_v1.commit request.
The workspace must belong to the ext_workspace_manager_v1 that was used to create this handle. Otherwise, this request raises the unknown_workspace error.
The client must not make this request if the handle does not have the set_workspace capability. Otherwise, this request raises the unsupported_feature error.
unassign_workspace(workspace: object<ext_workspace_handle_v1>)
Argument | Type | Description |
|---|---|---|
| workspace | object<ext_workspace_handle_v1> |
Request that the toplevel associated with this handle is unassigned from the given workspace. This request is double-buffered and applied on the next ext_workspace_foreign_toplevel_handle_v1.commit request.
The workspace must belong to the ext_workspace_manager_v1 that was used to create this handle. Otherwise, this request raises the unknown_workspace error.
The client must not make this request if the handle does not have the set_workspace capability. Otherwise, this request raises the unsupported_feature error.
commit()
The client must send this request after it has finished sending other requests. The compositor must process a series of requests preceding a commit request atomically.
This allows changes to the toplevel properties to be seen as atomic, even if they happen via multiple requests, and even if they involve multiple workspaces.
destroy()
Destroys the ext_workspace_foreign_toplevel_handle_v1 object.
enter_workspace(workspace: object<ext_workspace_handle_v1>)
Argument | Type | Description |
|---|---|---|
| workspace | object<ext_workspace_handle_v1> |
This event is emitted whenever the toplevel is assigned to a workspace. This event is double-buffered and applied on ext_foreign_toplevel_handle_v1.done event.
leave_workspace(workspace: object<ext_workspace_handle_v1>)
Argument | Type | Description |
|---|---|---|
| workspace | object<ext_workspace_handle_v1> |
This event is emitted whenever the toplevel is unassigned from a workspace. This event is double-buffered and applied on ext_foreign_toplevel_handle_v1.done event.
capabilities(capabilities: uint<ext_workspace_foreign_toplevel_handle_v1.capabilities>)
Argument | Type | Description |
|---|---|---|
| capabilities | uint<ext_workspace_foreign_toplevel_handle_v1.capabilities> | capabilities |
This event advertises the capabilities supported by the compositor. If a capability isn't supported, clients should hide or disable the UI elements that expose this functionality.
Compositors must send this event once after creation of an ext_workspace_foreign_toplevel_handle_v1. When the capabilities change, compositors must send this event again.
error { unsupported_feature, unknown_workspace }
Argument | Value | Description |
|---|---|---|
| unsupported_feature | 0 | request not supported |
| unknown_workspace | 1 | workspace is unknown |
capabilities { set_workspace }
Argument | Value | Description |
|---|---|---|
| set_workspace | 1 | assign_workspace and unassign_workspace request is available |
Compositor Support
Copyright
Copyright © 2025 Hiroaki Yamamoto
Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of the copyright holders not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. The copyright holders make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.