diff --git a/protocols/shell-workspace-creation-v1.xml b/protocols/shell-workspace-creation-v1.xml new file mode 100644 index 0000000..74d3018 --- /dev/null +++ b/protocols/shell-workspace-creation-v1.xml @@ -0,0 +1,351 @@ + + + + Copyright © 2025 outfoxxed + + 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. + + + + Many compositors make use of workspaces that are created dynamically + based on content or focus. This protocol aims to allow creation of + workspaces in such environments by combining the intent to create + a workspace with actions suitable to create one. + + This protocol additionally aims to make any logical workspace location + or workspace type available to the client, through globals defined + in this protocol or compositor-specific companion protocols. + + A client may attempt to discover potential creation methods by + creating new workspace targets, checking their capabilities and + destroying them without use. + + The key words "must", "must not", "required", "shall", "shall not", + "should", "should not", "recommended", "may", and "optional" in this + document are to be interpreted as described in IETF RFC 2119. + + Warning! The protocol described in this file is intended as a stopgap + and is expected to be superseded by a solution in wayland-protocols. + Clients should not assume this protocol will continue to exist in the + future. + + + + + The workspace creation target descriptor is an opaque object + that describes where and how a workspace will be created. + + Because shell_workspace_creation_target_descriptor_v1 objects + are created from multiple independent factory interfaces, + the shell_workspace_creation_target_descriptor_v1 interface + is frozen at version 1. + + + + + Destroy the object. + + + + + + + Allows the creation of workspace targets. + + + + + Destroy the manager. Destroying the manager does not destroy objects + created by the manager. + + + + + + This request creates a new workspace target from a given workspace + target descriptor. + + The descriptor may be destroyed following this request. + + Because the target descriptor cannot be versioned, this request + is used to create a versionable target from the descriptor. + + + + + + + + + + + Destroy the manager. Destroying the manager does not destroy objects + created by the manager. + + + + + + This requests creates a workspace target that targets an arbitrary, + compositor chosen location for the workspace within the given workspace + group, or any group if the no group was given. + + + + + + + + + + + Destroy the manager. Destroying the manager does not destroy objects + created by the manager. + + + + + + This request creates a workspace target at the given coordinates in + the workspace group's coordinate space. This coordinate space + should match the one used in 'ext_workspace_handle_v1.coordinates'. + + A given set of coordinates may be unrepresentable or otherwise disallowed + by the compositor, in which case the workspace target will be invalid. + + If a workspace already exists at the given coordinates, the resuling + target should be valid and refer to the existing workspace. + + + + + + + + + + + + Destroy the manager. Destroying the manager does not destroy objects + created by the manager. + + + + + + This request creates a workspace target adjacent to the given workspace + in the workspace group's coordinate space. The workspace coordinate space + should match the one used in 'ext_workspace_handle_v1.coordinates'. + + The provided offset must be one of [-1, 0, 1] for each axis supported by + the compositor to be valid, however other offsets may be unrepresentable + or otherwise disallowed by the compositor, in which case the workspace + target will be invalid. + + + + + + + + + + + + Destroy the manager. Destroying the manager does not destroy objects + created by the manager. + + + + + A workspace creation target is a target for actions that may create a new workspace + if performed. It may refer to either an existing workspace, or act as a marker + of where and how a new workspace should be created. + + + + + Destroy the workspace target. Destroying the target does not + cancel committed requests. + + + + + + + + + + + + + + + + This event updates the capabilities of the workspace target. + It must be sent upon creation of the target, and may be + sent again at any point thereafter. + + A workspace target without any capabilities is considered to be + invalid. An invalid target may be provided by the compositor + if an unrepresentable, disallowed, or otherwise invalid workspace + target is requested by the client. + + Clients are not required to check the capabilities of the target + before attempting to use them, but such uses must result in failure. + + + + + + + + This event reports that a requested action was successful. + + Reported 'success' and 'failed' events correspond to actions + in the order they were requested. + + + + + + This event reports that a requested action was not successful. + This may be due to a missing capability or any other compositor + determined reason. + + Reported 'success' and 'failed' events correspond to actions + in the order they were requested. + + + + + + This request submits a sequence of creation actions to be + performed atomically. + + Additional creation actions may be specified using + a compositor-specific extension protocol. + + Following this request, the client will receive a series of 'success' + or 'failed' events corresponding to the requested actions. + + The client may destroy the target object following this request if it + does not care about the results of the actions or wishes to determine + them in another way. + + + + + + Asks the compositor to create the workspace target. + This request is redundant if any other action is requested. + + This request must not take effect until committed. + + A 'success' or 'failed' event must be sent in response to this + following a commit. The request should be considered successful + if the workspace exists following the request, regardless + of if its creation was a result of this request. + + + + + + Asks the compositor to give a name to the targeted workspace. + + If the 'by_name' capability is present, assigning a name to the + workspace is enough to ensure its creation. The workspace may + still accept a name if the 'nameable' capability is present. + + This request must not take effect until committed. + + A 'success' or 'failed' event must be sent in response to this + following a commit. The request should be considered successful + if the workspace is active following the request, regardless + of if its activation was a result of this request. + + + + + + + + Asks the compositor to activate the workspace target. + + This request must not take effect until committed. + + A 'success' or 'failed' event must be sent in response to this request, + following a commit. The request should be considered successful + if the workspace is active following the request, regardless + of if its activation was a result of this request. + + + + + + Asks the compositor to move the given toplevel to the workspace + target. This request should not activate the target workspace + without an additional 'activate' request. + + This request must not take effect until committed. + + A 'success' or 'failed' event must be sent in response to this request, + following a commit. The request should be considered successful + if the toplevel is present on the workspace following the request, + regardless of if its presence was a result of this request. + + + + + + + + Asks the compositor to move an existing workspace to the + location specified by this workspace target. This request should + not activate the workspace without an additional 'activate' request. + + This request must not take effect until committed. + + A 'success' or 'failed' event must be sent in response to this request, + following a commit. The request should be considered successful if + the given workspace is in the targeted location following the request, + regardless of if its presence was a result of this request. + + + + + +