Zones

除了销毁 xx_zone_manager 对象外，此操作没有其他效果。

从 'xdg_toplevel' 创建一个新的可定位区域项。生成的包装对象可用于在区域中定位 toplevel 窗口。

创建一个新区域。在区域对象存在期间，合成器必须将其视为"已使用"并进行跟踪。

区域由字符串"句柄"表示。

合成器必须在任何客户端引用相应区域时保持区域句柄有效。合成器可以始终为给定输出给客户端相同的区域，并记住该区域的位置和大小，但客户端不应依赖此行为。

客户端可以通过传递 wl_output 作为 'output' 来请求将区域放置在特定输出上。如果设置了有效的输出，合成器应将该区域放置在该输出上。如果传递 NULL，则由合成器决定输出。

合成器应根据自己的策略为客户端提供最大合理区域空间。

如果合成器想要拒绝创建区域（例如在特定输出上），返回的区域必须是"无效的"。如果区域大小为负数，则该区域是无效的，在这种情况下禁止客户端在其中放置项。

使用区域的句柄创建新的区域对象。对于返回的区域，与 'get_zone' 中描述的规则相同。

此请求返回由 'handle' 表示的现有或已记住区域的引用。该区域可能是由不同的客户端创建的。

这允许协作的客户端共享相同的坐标空间。

如果区域句柄无效或未知，则必须创建并返回一个新区域，遵循 'get_zone' 中概述的规则，并假设没有输出偏好。

此请求创建的每个新区域对象都会发出其初始事件序列，包括 'handle' 事件，在无法加入现有区域的情况下，该事件必须返回与此请求中传递的句柄不同的句柄。

销毁区域项。客户端可以在任何时间发送此请求。通过销毁对象，相应的项表面保留在其最后位置，但与其区域的关联将丢失。这也将导致其丢失此协议描述的任何其他附加状态。

如果在此请求发送时项与区域关联，合成器必须在相应区域上发出 'item_left'，除非在 'closed' 事件之前已经发出。

请求将指定项表面放置在首选位置 (x, y)，相对于其关联的区域。此状态是双缓冲的，在 'item' 代表的表面的下一次 wl_surface.commit 时应用。

X 和 Y 坐标相对于该项关联的区域，不得大于区域大小设置的尺寸。它们可以小于零，如果项的左上角要放置在区域左上侧之外，但客户端应预期合成器在这种情况下会更积极地清理坐标值。

如果坐标超出区域的最大边界，合成器必须将其清理为更合适的值（例如通过将值限制在最大尺寸内）。对于无限区域，客户端可以选择任何坐标。

实现此协议的合成器应尝试将项放置在相对于项区域的请求坐标处，除非合成器策略不允许这样做。

客户端应意识到其放置偏好可能不会始终被遵循，并且必须准备好处理合成器将项放置在不同位置的情况。

一旦项被映射，仍然可以请求更改其首选放置位置并应当应用，但在用户与受影响的项表面交互时（例如在窗口内点击和拖动，或调整大小），合成器不得遵循该更改。

调用此请求后，必须发出带有项新实际位置的 'position' 事件。如果当前项没有关联的区域，必须发出 'position_failed' 事件。

'frame_extents' 事件描述了围绕项内容区域的框架的当前范围。

此事件在项加入区域后立即发送，或者如果项框架范围已被其他方式更改（例如由客户端请求触发或合成器参与）。尺寸使用与项区域相同的坐标空间（表面坐标空间）。

此事件之后必须跟随 'position' 事件，即使项的坐标没有因框架范围更改而改变。

如果项没有关联的框架，仍应发送此事件，但范围必须设置为零。

此事件仅在项当前与区域关联时才能发出。

此事件通知客户端项相对于其区域的当前位置 (x, y)。坐标相对于该项所属的区域，仅在其中有效。如果用户将项表面移动到区域左上边界之外，则可能出现负坐标。

此事件是响应 'set_position' 请求发送的，或者如果项位置已被其他方式更改（例如用户交互或合成器参与）。

此事件仅在项当前与区域关联时才能发出。

合成器无法完全设置此项的位置，甚至无法找到清理后的坐标来放置该项。

如果在项没有关联区域时调用了 'set_position'，也会发出此事件。

此事件表示此区域项包装的表面已被销毁。

'xx_zone_item_v1' 对象变为惰性，客户端应销毁它。合成器必须静默忽略对惰性区域项的任何请求，并且不会为此项发送更多事件。

如果在此事件发送时项与区域关联，合成器还必须在发送此事件之前在相应区域上发出 'item_left'。

使用此请求，客户端可以告诉合成器它不再使用 'xx_zone' 对象。只有在没有其他客户端当前引用该区域时，区域本身才必须被销毁，因此此请求可能只销毁客户端拥有的对象引用。

使 'item' 成为此区域的成员。此状态是双缓冲的，在 'item' 代表的表面的下一次 'wl_surface.commit' 时应用。

此请求将项与此区域关联。如果此请求在已与不同区域有区域关联的项上调用，该必须离开其旧区域（在其旧区域上发出 'item_left'），并将与此区域关联。

收到此请求后，如果目标区域允许 'item'，合成器必须发出 'item_entered' 以确认区域关联。即使项之前已与此区域关联，也必须发出此事件。

合成器必须在收到此请求并接受后，将 'item' 代表的表面移入此区域的边界内。

如果合成器不允许项切换区域关联，并希望其留在先前的区域中，则必须改为发出 'item_blocked'。

一旦 'item' 被添加到其区域，合成器必须首先在项上发送 'frame_extents' 事件，然后发送带有项当前位置的初始 'position' 事件。只要项与区域关联，合成器就必须在项在其区域中的位置发生变化时发送 'position' 事件。

如果区域无效，必须引发 'invalid' 错误，不得将项与无效区域关联。

如果引用的项是惰性的（其底层表面已被销毁），则必须静默忽略该请求。

移除 'item' 作为此区域的成员。此状态是双缓冲的，在 'item' 代表的表面的下一次 'wl_surface.commit' 时应用。

此请求显式地将项从此区域中移除，使客户端无法再次检索坐标。

收到此请求后，合成器不应更改屏幕上项表面的位置，并且必须发出 'item_left' 以确认项的移除。即使项从未与此区域关联，也必须发出此事件。

如果引用的项是惰性的（其底层表面已被销毁），则必须静默忽略该请求。

'size' 事件描述了此区域的大小。

它是一个矩形，原点在左上角，使用表面坐标空间（设备像素除以此区域所附加输出的缩放因子）。

如果宽度或高度值为零，则该区域在该方向上是无限的。

如果宽度和高度值为负，则该区域被视为"无效"，不得使用。声明区域无效的 size 事件只能在区域创建后立即发出。区域不得在之后通过发送负 'size' 而变为无效。

'size' 事件在创建 'xx_zone_v1' 后立即发送，以及区域大小每次更改时发送。区域大小可以随时因任何原因更改，例如由于输出大小或缩放更改，或由于合成器策略。

在 'xx_zone' 已创建后再次发出 'size' 时，不需要再次发送 'done' 事件。

handle 事件提供此区域的唯一句柄。该句柄可以与任何客户端共享，然后客户端可以通过调用 'xx_zone_manager.get_zone_from_handle' 使用它来加入此客户端的区域。

此事件必须在区域创建后仅发出一次。如果此区域无效，句柄必须是空字符串。

此事件在 'xx_zone' 的所有其他属性（大小、句柄）发送完毕后发出。

这允许将 xx_zone 属性的更改视为原子操作，即使它们通过多个事件发生。

此事件通知客户端某项被阻止加入此区域。

如果合成器不允许该项加入此特定区域，作为对 'add_item' 的响应发出。

此事件通知客户端某项加入了此区域。

作为对 'add_item' 的响应发出，或者如果合成器自动让项表面（重新）加入现有区域。

此事件通知客户端某项离开了此区域，因此客户端将不再接收该项的更新坐标或框架范围。如果客户端仍希望调整项表面坐标，可以通过调用 'add_item' 将项与区域重新关联。

例如，如果用户将项表面移出较小区域的边界，或移至先前区域无法扩展到的不同屏幕，会发出此事件。它也在响应通过 'remove_item' 显式移除项时发出。