Input method v2

对此文本输入执行操作。

通过此事件设置的值是双缓冲的。它们必须在下一个 commit 请求时应用并重置为初始值。

action 的初始值为 none。

发送提交字符串文本以插入到应用程序中。

在当前光标位置插入字符串（参见 commit 事件序列）。要提交的字符串可以是按键后的单个字符，也可以是某些组合的结果。

参数 text 是一个包含要插入字符串的缓冲区。Wayland 消息有最大长度限制，因此 text 不能超过 4000 字节。

通过此请求设置的值是双缓冲的。它们必须在下一个 .commit 请求时应用并重置为初始值。

text 的初始值为空字符串。

向应用程序文本输入发送预编辑字符串文本。

在当前光标位置放置新的组合文本（预编辑）。必须删除任何先前设置的组合文本。必须删除任何先前存在的选定文本。光标移动到预编辑字符串内的新位置。

参数 text 是一个包含预编辑字符串的缓冲区。Wayland 消息有最大长度限制，因此 text 不能超过 4000 字节。

参数 cursor_begin 和 cursor_end 以字节为单位，相对于提交的字符串缓冲区的开头计算。当两者都等于 -1 时，文本输入应隐藏光标。

cursor_begin 表示光标的开始。cursor_end 表示光标的结束。它可以等于或不同于 cursor_begin。

通过此请求设置的值是双缓冲的。它们必须在下一个 xx_input_method_v1.commit 请求时应用。 它们必须在下一个已提交的 .deactivate 事件时重置为初始值。

text 的初始值为空字符串。cursor_begin 和 cursor_end 的初始值均为 0。

删除周围文本。

before_length 和 after_length 是当前光标索引之前和之后要删除的字节数（不包括预编辑文本）。

如果文本被选定，则必须删除它。

如果索引超过可用文本边界，应调整它们以适应边界并重新尝试删除。如果索引不在字节边界上，则文本输入客户端应删除至少那么多字节。在这种情况下，客户端决定结束点，但建议使用与使用键盘删除时相同的字符边界。

如果存在任何预编辑文本，则为此事件将其替换为光标。实际上，before_length 从预编辑文本的开头计算，after_length 从其结尾计算（参见 commit 事件序列）。

通过此请求设置的值是双缓冲的。它们必须在下一个 xx_input_method_v1.commit 请求时应用并重置为初始值。

before_length 和 after_length 的初始值均为 0。

取消选择文本，移动光标并选择文本。

这相当于在文本上拖动鼠标：它取消选择当前可能选定的任何内容并选择新的文本范围。

参数中使用的偏移量以字节为单位，相对于当前光标位置。Cursor 是光标的新位置，anchor 是选择的另一端。如果没有选择，anchor 应等于 cursor。

偏移量不考虑预编辑内容，此请求也不会以任何方式更改预编辑。

cursor 和 anchor 都必须位于代码点边界上，否则文本输入客户端可能会忽略请求。因此不建议输入法将它们中的任何一个移动到 surrounding_text 中接收的文本之外。

当不支持 surrounding_text 时，偏移量不得解释为字节，而是解释为至少与代码点一样大的人类可读单位，例如字素。

cursor 和 anchor 参数还可以采用以下特殊值： BEGINNING := 0x8000_0000 = i32::MIN END := 0x7fff_ffff = i32::MAX 分别表示输入字段中所有文本的开头和结尾。

通过此事件设置的值是双缓冲的。它们必须在下一个 commit 请求时应用并重置为初始值。

cursor 和 anchor 的初始值均为 0。

应用来自 commit_string、set_preedit_string 和 delete_surrounding_text 请求的状态更改。

与这些事件相关的状态是双缓冲的，每个事件都会修改待处理状态。此请求用待处理状态替换当前状态。

连接的文本输入应按以下顺序评估更改：

1. 用光标替换现有的预编辑字符串。 2. 删除请求的周围文本。 3. 在光标位于其末尾的情况下插入提交字符串。 4. 移动光标和选择。 5. 计算要发送的周围文本。 6. 在光标位置插入新的预编辑文本。 7. 将光标放在预编辑文本内。 8. 执行请求的操作。

请注意，输入法接收的选定文本不能超过 4000 字节，例如当选择了整个文档时可能会出现这种情况。尽管如此，文本输入必须在插入提交字符串之前删除整个选定范围。

protocol_compat == xx_text_input 时的序列号处理

序列号应设置为 0。

protocol_compat == text_input_v3 时的序列号处理

序列号反映客户端已知的 xx_input_method_v1 对象的最后状态。serial 参数的值必须等于该对象已发出的 done 事件的数量。当 compositor 收到的 commit 请求的序列号与过去的 done 事件数量不同时，它必须照常进行，但不应更改 xx_input_method_v1 对象的当前状态。

创建一个新的 xx_input_popup_surface_v2 对象，包装给定的 surface。

该 surface 被分配 "input_popup" 角色。如果该 surface 已经有分配的角色，compositor 必须发出协议错误。

在接收到已提交的 .activate 之前发出此请求会导致 "inactive" 错误。

销毁 xx_input_method_v1 对象及任何关联的子对象。

通知在此 seat 上聚焦的文本输入请求激活输入法。

此事件的目的是为 compositor 提供一个活跃的输入法。

此事件重置与先前 surrounding_text、text_change_cause 和 content_type 事件相关的所有状态，以及与 set_preedit_string、commit_string 和 delete_surrounding_text 请求相关的状态，并销毁任何现有的 input_popup_surface 对象。此外，它将 xx_input_method_v1 对象标记为活跃。

如果文本输入支持相应功能，surrounding_text 和 content_type 事件必须在下一个 done 事件之前发送。

通过此事件设置的状态是双缓冲的。它将在下一个 xx_input_method_v1.done 事件时应用，并保持有效直到更改。

通知当前没有聚焦的文本输入需要在此 seat 上活跃的输入法。

此事件将 xx_input_method_v1 对象标记为非活跃。compositor 必须销毁所有现有的 xx_input_popup_surface_v2 对象。

此事件重置与先前 surrounding_text、text_change_cause 和 content_type 事件相关的所有状态，以及与 set_preedit_string、commit_string 和 delete_surrounding_text 请求相关的状态。

通过此事件设置的状态是双缓冲的。它将在下一个 xx_input_method_v1.done 事件时应用，并保持有效直到更改。

更新光标周围的纯文本，不包括预编辑文本。

如果存在任何预编辑文本，则为此事件将其替换为光标。

参数 text 是一个包含预编辑字符串的缓冲区，必须包含光标位置和完整的选择。它应在这些内容前后包含额外的字符。Wayland 消息有最大长度限制，因此 text 不能超过 4000 字节。

cursor 是文本缓冲区中光标的字节偏移量。

anchor 是文本缓冲区中选择锚点的字节偏移量。如果没有选定文本，anchor 必须与 cursor 相同。

如果此事件在第一个 done 事件之前未到达，输入法可以假设文本输入不支持此功能，并忽略后续的 surrounding_text 事件。

通过此事件设置的值是双缓冲的。它们将在下一个 xx_input_method_v1.done 事件时应用并设置为初始值。

受影响字段的初始状态为空，表示文本输入不支持发送周围文本。如果应用了空值，后续更改它们的尝试可能不会生效。

告知输入法光标周围文本更改的原因。

每当客户端检测到文本、光标或锚点位置的外部更改时，它必须向 compositor 发出此请求。此请求旨在让输入法有机会以适当的方式更新预编辑文本，例如当用户开始使用键盘输入时将其删除。

cause 描述更改的来源。

通过此事件设置的值是双缓冲的。它将在下一个 xx_input_method_v1.done 事件时应用并设置为初始值。

cause 的初始值为 input_method。

指示当前 xx_input_method_v1 实例的内容类型和提示。

通过此事件设置的值是双缓冲的。它们将在下一个 xx_input_method_v1.done 事件时应用。 它们在下一个已提交的 deactivate 事件时重置为初始值。

hint 的初始值为 none，purpose 的初始值为 normal。

通告当前活跃文本输入可用的操作。

通过此事件设置的值是双缓冲的。它们将在下一个 .done 事件时应用。 它们在下一个已提交的 deactivate 事件时重置为初始值。

初始值为空集：没有可用的操作。

available_actions 数组中的值来自 text-input-v3.action。

通知输入法当前活跃的文本输入客户端能够做什么。

此事件应与 .activate 在同一个 .done 序列中发送。否则，输入法可能会忽略它。

通过此事件设置的值是双缓冲的。它们将在下一个 .done 事件时应用。 它们在下一个已提交的 deactivate 事件时重置为初始值。

features 的初始值为 none。

告知输入法客户端文本输入客户端支持哪些类型的事件。

通过此事件设置的值是双缓冲的。它们将在下一个 .done 事件时应用。 它们在下一个已提交的 deactivate 事件时重置为初始值。

compositor 可以将此事件作为从非活跃切换到活跃状态的 .done 链的一部分发送。除此之外不得发送此事件。

version 的初始值为 text_input_v3。

原子地应用最近发送给客户端的状态更改。

done 事件建立并更新客户端的状态，必须在任何更改后发出以应用它们。

文本输入状态（内容用途、内容提示、周围文本和更改原因）在输入法上下文中是概念上双缓冲的。

事件修改待处理状态，而不是输入法使用的当前状态。done 事件原子地应用所有待处理状态，替换当前状态。done 之后，新的待处理状态如每个相关请求所记录。

事件必须按到达顺序应用。

除非另有说明，否则当前状态和待处理状态都不会被修改。

输入法不再可用。

如果在创建时同一 seat 关联了另一个 input_method 对象，compositor 必须将此事件作为对象上的唯一事件发出。

当对象不再可用时（例如由于 seat 被移除），compositor 必须发出此请求。

输入法上下文变为无效，应在处理 deactivate 后销毁。除 destroy 请求外，必须忽略任何进一步的请求和事件。

告知输入法客户端文本输入客户端支持哪些类型的事件。

此请求通知 compositor 客户端已更新其 surface 以响应 configure 序列。

此请求的目的是同步 surface 几何形状与 surface 内容的更新。例如，当 compositor 分配了比以前更大的尺寸时，客户端必须在弹出窗口以新尺寸显示给用户之前填充额外的空间。当 compositor 收到 .ack_configure 时，它可以继续绘制新尺寸。

.ack_configure 应在每次提交的 configure 序列之后发送，传递其中接收到的 serial。

.ack_configure 请求在概念上是双缓冲的。 每个请求都会覆盖前一个请求。一旦在对应的 surface 上发送 .commit 请求，该请求就会生效。

如果客户端在能够响应一个 configure 序列之前收到多个 configure 序列，它可以通过在 .ack_configure 请求中使用最后一个 configure 序列的 serial 来仅确认最后一个 configure 序列。

提交 .ack_configure 请求会消耗该请求附带的 serial 号，以及在此 input_popup_surface 上提交的、在被引用的 serial 之前的 configure 序列发送的所有 serial 号。

提交此请求时使用的 serial 如果从未出现在此 surface 的 configure 序列中，或者之前已被提交过，会引发 invalid_serial 错误。

重新定位已映射的弹出窗口。弹出窗口将根据传入的 input_popup_positioner 对象中的详细信息放置。

该请求会立即处理，无需发出 wl_surface.commit，但实际的重新定位稍后在 .ack_configure 之后进行。

compositor 应回复一个 configure 序列，包括：

• input_popup_surface.start_configure,
• input_popup_surface.repositioned，包括此请求中传入的 token。

这将丢弃先前 positioner 设置的任何参数。

如果在 .repositioned 事件作为 configure 序列的一部分提交之前发送了多个 .reposition 请求，compositor 可以忽略除最后一个之外的所有请求。

新的弹出窗口位置在客户端确认相应的 configure 序列之前不会生效。详见 input_popup_surface.repositioned。

token 本身是不透明的，没有其他特殊含义。

这会销毁弹出窗口。显式销毁 input_popup_surface 对象也会关闭弹出窗口并取消映射 surface。

start_configure 事件更新弹出窗口的几何形状并标记 configure 序列的开始。

anchor_* 参数表示弹出窗口所附加到的锚点的几何形状，相对于弹出窗口 surface 的左上角。请注意，这使得 anchor_x、anchor_y 与 xdg_popup 中表示的相反。

configure 序列是一组配置 input_popup_surface 状态的一个或多个事件，从此事件开始，以 input_method.done 结束。在 input_method.done 事件之后，configure 序列被视为已提交。

在 configure 序列中由事件设置的状态在概念上是双缓冲的。 每个参数都会覆盖其先前的值。状态更改应与结束序列的 input_method.done 原子地应用，并且 serial 的值应返回到未定义值。

在 configure 序列之外（当 serial 未定义时）接收到的 input_popup_surface 对象上的事件必须被客户端忽略。

每当 compositor（重新）定位弹出窗口或锚点的形状发生变化时（例如在弹出窗口创建之后，或响应输入文本和文本光标移动），应发送 configure 序列。

客户端可以响应 input_method.done 更新 surface。除非弹出窗口被 input_method.done 销毁，否则客户端必须在序列结束后且提交新 surface 之前的某个时间点回复带有 start_configure 事件中发送的 serial 的 .ack_configure 请求。

如果客户端在能够响应一个 configure 序列之前收到多个 configure 序列，它可以自由丢弃除最后一个接收到的事件之外的所有事件。

compositor 发送 .repositioned 事件以响应 .reposition 请求，通知其完成。

弹出窗口的新几何形状可以使用 configure 序列中的附加事件来传达，包括：

• input_popup_surface.start_configure，和
• .anchor_position 事件以更新相对于锚点的相对位置。

当响应 .reposition 请求时，token 参数是该请求中传入的 token。

此事件作为 configure 序列的一部分发送。 此事件设置的状态在概念上是双缓冲的。 每个参数都会覆盖其先前的值。状态更改应与下一个 input_method.done 事件原子地应用。

客户端可以选择更新弹出窗口的内容，但必须确认新的弹出窗口配置才能使新位置生效。详见 input_popup_surface.ack_configure。

通知 compositor positioner 将不再使用。

设置要使用 positioner 对象定位的 surface 的尺寸。尺寸以 surface 局部坐标给出，对应于窗口几何形状。参见 xdg_surface.set_window_geometry。

如果任一维度设置为零，将引发 invalid_input 错误。

定义锚点矩形的锚点。指定的锚点用于派生弹出 surface 将相对于其定位的锚点。如果设置了角锚点（例如 'top_left' 或 'bottom_right'），锚点将在指定的角落；否则，派生的锚点将在指定边缘的中心，或者如果未指定边缘则在锚点矩形的中心。

定义 surface 应相对于锚点矩形的锚点放置的方向。如果指定了角重力（例如 'bottom_right' 或 'top_left'），则 surface 将朝向指定的重力方向放置；否则，子 surface 将在任何未指定重力的轴上居中于锚点。如果重力不在 'gravity' 枚举中，将引发 invalid_input 错误。

指定如果原始预期位置导致 surface 被约束（意味着至少部分在 compositor 设置的定位边界之外）时应如何调整弹出窗口。通过构建位掩码来设置调整，描述当 surface 在该轴上被约束时要进行的调整。

如果未为某个轴设置任何位，compositor 将假设子 surface 在被约束时不应更改其在该轴上的位置。

如果为某个轴设置了多个位，调整的应用顺序在相应的调整描述中指定。

默认调整为 none。

指定 surface 位置相对于锚点矩形上的锚点和 surface 上的锚点的偏移量。例如，如果锚点矩形的锚点在 (x, y)，surface 具有重力 bottom|right，偏移量为 (ox, oy)，则计算出的 surface 位置将为 (x + ox, y + oy)。surface 的偏移位置是用于约束测试的位置。参见 set_constraint_adjustment。

一个示例用例是将弹出菜单放置在用户界面元素的顶部，同时将父 surface 的用户界面元素与弹出 surface 中某处放置的某个用户界面元素对齐。

设置为响应式时，如果用于约束的条件发生变化（例如包含文本输入的窗口移动），surface 将被重新约束。

每当条件发生变化且弹出窗口被重新约束时，会发送带有更新几何形状的 configure 序列。

约束调整值定义了当未调整的位置会导致 surface 部分被约束时，compositor 调整 surface 位置的方式。

surface 是否被视为“受约束”由 compositor 确定。例如，surface 可能部分在 compositor 定义的“工作区域”之外，因此需要调整子 surface 的位置直到其完全在工作区域内。

这些调整可以组合，按照定义的优先级：1) 翻转，2) 滑动，3) 调整大小。

请求与给定 seat 关联的新输入 xx_input_method_v1 对象。

创建一个 positioner 对象。positioner 对象用于相对于某个父 surface 定位 surface。详见接口描述和 xdg_surface.get_popup。

销毁 xx_input_method_manager_v2 对象。

由其发起的 xx_input_method_v1 对象仍然有效。