AGL shell
agl_shell
从协议版本 2 开始，客户端需要等待 'bound_ok' 或 'bound_fail' 事件才能继续操作。
如果客户端收到 'bound_fail' 事件，则应认为已有另一个客户端绑定到 agl_shell 协议。收到 'bound_ok' 事件的客户端应认为没有其他客户端绑定到该接口，可以继续操作。
如果客户端使用较旧版本的协议，当有另一个客户端已绑定该接口时，它将自动收到错误，合成器将终止连接。
如果客户端收到 'bound_fail' 事件并尝试进一步使用该接口，它将收到错误，合成器将终止连接。收到 'bound_fail' 事件后，客户端应调用析构器（已在协议版本 2 中添加）。客户端可以稍后重试以查看是否会收到 'bound_ok' 事件，但没有明确的方式得知该事件何时会送达。假设它可以通过其他方式/其他渠道推断该信息。
ready()
告知服务器此客户端已准备好显示。服务器将在启动期间延迟显示，直到所有 shell 客户端都准备好显示，并将显示黑屏。这使客户端有机会设置和配置多个表面为一个连贯的界面。
绑定到此接口的客户端必须发送此请求，否则可能会不必要地阻塞合成器。
如果在合成器已完成启动后调用此请求，则不执行任何操作。
set_background(surface: object<wl_surface>, output: object<wl_output>)
参数 | 类型 | 描述 |
|---|---|---|
| surface | object<wl_surface> | |
| output | object<wl_output> |
将表面设置为输出的背景。发送此请求后，服务器将立即发送一个配置事件，其中包含客户端应用于覆盖整个输出的尺寸。
表面必须具有 libweston-desktop 支持的"桌面"表面角色。
单个表面只能是一个输出的背景。如果背景表面已存在，则引发协议错误。
set_panel(surface: object<wl_surface>, output: object<wl_output>, edge: uint<agl_shell.edge>)
参数 | 类型 | 描述 |
|---|---|---|
| surface | object<wl_surface> | |
| output | object<wl_output> | |
| edge | uint<agl_shell.edge> |
将表面设置为输出的面板。'edge' 参数指定表面将锚定到输出的哪个边缘。发送此请求后，服务器将发送一个配置事件，其中包含客户端应使用的相应宽度/高度，另一个维度为 0。例如，如果边缘为 'top'，则宽度为输出的宽度，高度为 0。
表面必须具有 libweston-desktop 支持的"桌面"表面角色。
合成器在定位其他窗口时将考虑面板的窗口几何形状，因此面板不会被覆盖。
XXX: 如果同时使用 top 和 left 会发生什么？谁获得角落？
单个表面只能是输出某个边缘的面板。如果表面上已存在面板，则引发协议错误。
请求合成器使某个顶层成为窗口管理的当前/聚焦窗口。
有关 app_id 的描述，请参见 xdg-shell 协议中的 xdg_toplevel.set_app_id。
如果多个顶层具有相同的 app_id，则结果未指定。
XXX: 我们是否需要反馈说它没有工作？（例如客户端不存在）
参数 | 类型 | 描述 |
|---|---|---|
| output | object<wl_output> | |
| x | int | x position of rectangle |
| y | int | y position of rectangle |
| width | int | width of rectangle |
| height | int | height of rectangle |
提示合成器使用自定义区域，而不是推断激活区域。如果使用了任何面板，合成器通过减去面板几何区域来计算激活区域。如果没有使用面板，则使用整个输出。此请求更改此行为，以提示合成器使用提供的矩形并忽略之前可能设置的任何面板。
为了使此请求生效，需要在 'ready' 请求之前发生，以便合成器能够使用它。请注意，如果调用了此请求，任何 'set_panel' 请求将不会被执行。
x 和 y 坐标使用左上角作为原点。矩形区域不应超出输出区域，而小于输出的区域将导致显示背景表面。
deactivate_app(app_id: string)
参数 | 类型 | 描述 |
|---|---|---|
| app_id | string |
请求合成器为窗口管理目的隐藏顶层窗口。根据窗口角色，此请求将显示先前活动的窗口（如果没有先前活动的表面则显示背景）或临时（或直到调用 'activate_app'）隐藏表面。
所有表面都可通过 app_id 标识，如果 app_id 不存在/未存在，则不执行任何操作。
有关 app_id 的描述，请参见 xdg-shell 协议中的 xdg_toplevel.set_app_id。
使由 app_id 标识的应用程序变为浮动状态。如果应用程序的窗口已映射，处于最大化、正常状态，它将转换为浮动状态。
对于想要修改自身状态的应用程序，此请求必须在初始表面提交之前完成才能生效。
如果应用程序已处于浮动状态，此请求不会执行任何操作。
此请求没有持久性，一旦应用程序终止，需要为该特定 app_id 再次发出此请求。
x 和 y 值将是窗口表面放置的初始位置。
有关 app_id 的描述，请参见 xdg-shell 协议中的 xdg_toplevel.set_app_id。
set_app_normal(app_id: string)
参数 | 类型 | 描述 |
|---|---|---|
| app_id | string |
将由 app_id 标识的应用程序恢复到正常状态。这对于从其他状态返回到最大化状态（应用程序启动时的正常状态）很有用。
set_app_fullscreen(app_id: string)
参数 | 类型 | 描述 |
|---|---|---|
| app_id | string |
使由 app_id 标识的应用程序变为全屏状态。如果应用程序的窗口已映射，处于最大化、正常状态，它将转换为全屏状态。
对于想要修改自身状态的应用程序，此请求必须在初始表面提交之前完成才能生效。
如果应用程序已处于全屏状态，此请求不会执行任何操作。
此请求没有持久性，一旦应用程序终止，需要为该特定 app_id 再次发出此请求。
有关 app_id 的描述，请参见 xdg-shell 协议中的 xdg_toplevel.set_app_id。
允许合成器将应用程序放置在特定输出上（如果该输出确实可用）。这可以在应用程序启动之前发生，使应用程序在该特定输出上启动。如果应用程序已启动，它将把应用程序移动到该输出。
此请求没有持久性，一旦应用程序终止，需要为该特定 app_id 再次发出此请求。
有关 app_id 的描述，请参见 xdg-shell 协议中的 xdg_toplevel.set_app_id。
客户端可以通知合成器将浮动类型的窗口定位到 x 和 y 值指定的特定位置。如果窗口不是浮动类型，请求将被丢弃。请注意，定位不考虑输出也不考虑输出的方向。预期客户端已经知道位置在全局坐标空间中的位置。如果窗口不存在，合成器将忽略此请求。为了使此请求正常工作，窗口需要先设置为浮动状态，然后才能使用此请求移动。
有关 app_id 的描述，请参见 xdg-shell 协议中的 xdg_toplevel.set_app_id。
客户端可以通知合成器将浮动类型的窗口缩放到 width 和 height 指定的值。如果窗口不是浮动类型，请求将被丢弃。如果窗口不存在，合成器将忽略此请求。为了使此请求正常工作，窗口需要先设置为浮动状态，然后才能使用此请求移动。
有关 app_id 的描述，请参见 xdg-shell 协议中的 xdg_toplevel.set_app_id。
set_app_split(app_id: string, orientation: uint<agl_shell.tile_orientation>, width: int, sticky: int, output: object<wl_output>)
参数 | 类型 | 描述 |
|---|---|---|
| app_id | string | |
| orientation | uint<agl_shell.tile_orientation> | |
| width | int | width of the window being split |
| sticky | int | make the split window stiky |
| output | object<wl_output> |
此请求要求合成器将应用程序从原始模式（无论是什么）更改为 tile_orientation 枚举中定义的分屏、平铺方向模式。客户端需要实现调整大小（以处理 xdg-shell 配置事件）才能使此功能正常工作。
出于实际原因，此请求仅处理单级平铺：保持实现简单直接。如果已经有两个窗口存在，合成器将忽略请求。客户端可以通过检查 xdg-shell 配置事件以及合成器发送的状态来验证此请求是否成功。
如果没有具有所提供名称的 app_id，合成器将把应用程序添加到待处理列表中，以便在应用程序启动时或应用程序在初始 wl_surface.commit 请求之后设置其应用程序时应用。
如果应用程序想要在创建 xdg-shell 顶层角色之前以平铺方向位置启动，可以使用此方法。
none 方向类型将使窗口返回到原始的最大化模式。如果两个窗口并排，将其中一个返回原始模式意味着另一个将被隐藏，请求 none 方向的窗口将成为当前活动窗口。使用 activate_app 请求进一步激活另一个窗口将使该窗口变为活动状态。
在平铺方向状态下关闭窗口意味着将显示背景表面，或者如果当时正在显示另一个应用程序，则将使该应用程序返回到原始的最大化状态。
平铺方向可以独立应用，因此客户端可以从一个平铺方向转换到另一个平铺方向。请注意，任何已存在的其他窗口将完全采用与当前正在更改的方向相反的方向。因此平铺方向...（行截断为 2000 字符）
app_state(app_id: string, state: uint<agl_shell.app_state>)
参数 | 类型 | 描述 |
|---|---|---|
| app_id | string | |
| state | uint<agl_shell.app_state> |
通知客户端应用程序已将其状态更改为 app_state 枚举指定的另一个状态。客户端可以使用此事件跟踪当前应用程序状态。例如了解应用程序何时启动，或何时终止/停止。
app_on_output(app_id: string, output_name: string)
参数 | 类型 | 描述 |
|---|---|---|
| app_id | string | |
| output_name | string |
客户端可以使用此事件在应用程序想要显示在某个输出上时收到通知。此事件是作为 set_app_output 请求的响应发送的。
有关 app_id 的描述，请参见 xdg-shell 协议中的 xdg_toplevel.set_app_id。
error { invalid_argument, background_exists, panel_exists }
app_state { started, terminated, activated, deactivated }
agl_shell_ext
此接口允许另一个客户端绑定到 agl_shell 接口，即使已有另一个 shell 客户端存在。
客户端应首先绑定到此接口，然后通过 'doas_shell_client' 请求通知合成器它想要绑定到 agl_shell 接口。如果使用新版本的 agl_shell 接口，客户端仍需要等待 'bound_ok' 和 'bound_fail' 事件，然后才能发出任何其他请求/事件。
请注意，此接口有其局限性，如果已有客户端使用了 agl_shell 接口的 'set_panel' 或 'set_background' 请求，合成器仍会拒绝执行这些请求。
任何其他请求或事件应像绑定到 agl_shell 接口的客户端一样被传递和处理。
destroy()
准备好 agl_shell_ext 接口后调用析构器。这将重置状态，并终止在 agl_shell 接口上发出的任何请求。客户端需要重新绑定 agl_shell_ext 并发出 'doas_shell_client' 请求。
doas_shell_client()
在绑定到 agl_shell 接口之前，此请求将通知合成器它想要获得 agl_shell 接口的访问权限。客户端需要等待 'doas_shell_client_done' 事件并检查成功状态，然后才能继续绑定到 agl_shell 接口。
doas_done(status: uint<agl_shell_ext.doas_shell_client_status>)
参数 | 类型 | 描述 |
|---|---|---|
| status | uint<agl_shell_ext.doas_shell_client_status> |
客户端应检查状态事件以验证合成器是否能够处理该请求。
合成器支持
Copyright
Copyright © 2019, 2022 Collabora, Ltd.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.