Text input

销毁 xx_text_input 对象。同时禁用通过此 xx_text_input 对象启用的所有 surface。

请求在之前从 enter 事件获取的 surface 上进行文本输入。

每次活动文本输入更改为新的输入时，必须发出此请求，包括在当前 surface 内。当当前 surface 上不再有任何输入焦点时，使用 xx_text_input_v3.disable。

客户端不得在单个 seat 上启用多个文本输入，应在启用新文本输入之前禁用当前文本输入。每个实例最多只能有一个文本输入实例处于启用状态，当某些文本输入处于活动状态时，启用另一个文本输入的请求必须被合成器忽略。

此请求重置与先前 enable、disable、set_surrounding_text、set_text_change_cause、set_content_type 和 set_cursor_rectangle 请求关联的所有状态，以及与 preedit_string、commit_string、delete_surrounding_text 和 action 事件关联的状态。

如果文本输入支持必要的功能，set_surrounding_text、set_content_type 和 set_cursor_rectangle 请求必须跟随之后。

通过此请求设置的状态是双缓冲的。它将在下一个 xx_text_input_v3.commit 请求时应用，并保持有效直到下一个提交的 enable 或 disable 请求。

更改必须在发出 xx_text_input_v3.commit 请求后由合成器应用。

显式禁用当前 surface 上的文本输入（通常当 surface 内没有任何文本输入字段获得焦点时）。

通过此请求设置的状态是双缓冲的。它将在下一个 xx_text_input_v3.commit 请求时应用。

设置输入周围的纯文本，不包括预编辑文本。

客户端应将此请求携带的任何值的任何更改通知合成器，包括处理传入文本输入事件引起的更改以及键盘输入等其他机制引起的更改。

如果客户端不知道光标周围的文本，则不应发出此请求，以向合成器表示不支持。

文本为 UTF-8 编码，应包含光标位置、完整选择以及它们前后的额外字符。Wayland 消息有最大长度限制，因此文本不能超过 4000 字节。

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

锚点是文本缓冲区内选择锚点的字节偏移量。如果没有选定文本，锚点与光标相同。

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

通过此请求设置的值是双缓冲的。它们将在下一个 xx_text_input_v3.commit 请求时应用，并保持有效直到下一个提交的 enable 或 disable 请求。

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

告知合成器光标周围的文本更改的原因。

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

cause 描述更改的来源。

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

cause 的初始值为 input_method。

设置内容用途和内容提示。用途是输入字段的基本用途，提示标志允许修改某些行为。

通过此请求设置的值是双缓冲的。它们将在下一个 xx_text_input_v3.commit 请求时应用。 后续更新尝试可能无效。这些值在下一个提交的 enable 或 disable 请求之前保持有效。

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

在 surface 局部坐标中将光标周围的区域标记为 x、y、width、height 矩形。

允许合成器将带有单词建议的窗口放在光标附近，而不妨碍正在输入的文本。

如果客户端不知道编辑文本的位置，则不应发出此请求，以向合成器表示不支持。

通过此请求设置的值是双缓冲的。它们将在下一个 xx_text_input_v3.commit 请求时应用，并保持有效直到下一个提交的 enable 或 disable 请求。

描述光标矩形的初始值为空。这意味着文本输入不支持描述光标区域。如果空值被应用，后续更改尝试可能无效。

原子性地应用最近发送到合成器的状态更改。

commit 请求建立和更新客户端的状态，必须在任何更改后发出以应用它们。

文本输入状态（启用状态、内容用途、内容提示、周围文本和更改原因、光标矩形）在文本输入的上下文中是概念性双缓冲的，即在提交的 enable 请求和以下提交的 enable 或 disable 请求之间。

协议请求修改待处理状态，而不是输入方法使用的当前状态。commit 请求原子性地应用所有待处理状态，替换当前状态。提交后，新的待处理状态如每个相关请求所记录。

请求按到达顺序应用。

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

合成器必须计算来自每个 xx_text_input_v3 对象的 commit 请求数量，并将该计数用作 done 事件中的序列号。

公布当前活动文本输入可用的操作。

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

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

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

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

此事件应在与 .activate 相同的 .done 序列中出现。否则，输入方法可能会忽略它。

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

features 的初始值为 none。

通知此 seat 的文本输入焦点在某个 surface 上。

如果客户端创建了多个文本输入对象，合成器必须将此事件发送给所有对象。

当 seat 具有键盘功能时，文本输入焦点跟随键盘焦点。此事件为文本输入对象设置当前 surface。

通知此 seat 的文本输入焦点不再在某个 surface 上。客户端应重置之前设置的任何预编辑字符串。

leave 通知清除当前 surface。它在新焦点的 enter 通知之前发送。leave 事件后，合成器必须忽略来自任何文本输入实例的请求，直到下一个 enter 事件。

当 seat 具有键盘功能时，文本输入焦点跟随键盘焦点。

通知应在当前光标位置设置新的组合文本（预编辑）。必须移除之前设置的任何组合文本。必须移除任何先前存在的选定文本。

参数 text 包含预编辑字符串缓冲区。

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

如果两个值相同，客户端可以将其表示为一行，否则表示为文本高亮。

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

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

通知何时应将文本插入编辑器部件。要提交的文本可以是按键后的单个字符，也可以是某些组合（预编辑）的结果。

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

text 的初始值为空字符串。

通知何时应删除当前光标位置周围的文本。

before_length 和 after_length 是当前光标索引之前和之后要删除的字节数（不包括选择）。

如果选择了文本，必须删除它。

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

如果存在预编辑文本，实际上 before_length 从其开头计算，after_length 从其末尾计算（请参阅 done 事件序列）。

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

before_length 和 after_length 的初始值均为 0。

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

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

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

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

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

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

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

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

cursor 和 anchor 的初始值均为 0。

指示应用程序应用 preedit_string、commit_string、delete_surrounding_text 和 action 事件请求的状态更改。 与这些事件相关的状态是双缓冲的，每个事件都会修改待处理状态。此事件用待处理状态替换当前状态。

应用程序必须按以下顺序评估和应用更改：

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

版本 2 及以上的序列号处理：

参数 "serial" 被忽略。

版本 1 的序列号处理：

序列号反映合成器已知的 xx_text_input_v3 对象的最后状态。serial 参数的值必须等于该对象上已发出的 commit 请求数量。

当客户端收到序列号与过去的 commit 请求数量不同的 done 事件时，必须照常继续评估和应用更改，但不应更改 xx_text_input_v3 对象的当前状态。在收到序列号匹配的 xx_text_input_v3.done 事件后，应发送并提交 xx_text_input_v3 对象上的所有待处理状态请求（set_surrounding_text、set_content_type 和 set_cursor_rectangle）。

输入方法发出了要在此文本输入上执行的操作。

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

action 的初始值为 none。

周围文本或光标位置更改的原因。

内容提示是允许修改文本输入行为的位掩码。

内容用途允许指定文本输入的主要用途。

这允许输入方法显示带有额外字符的特殊用途输入面板或禁止某些字符。

可在文本输入上执行的可能操作。

超出基线的客户端功能，不是隐式指示的。

这不包括随 .enable 一起出现的事件：当输入方法收到此类事件时，很明显文本输入支持它，例如 content_type、available_actions。

像 commit_string、set_preedit_string 这样的基线功能必须始终被支持，协议才有用。

这些标志匹配文本输入协议版本，但应保持足够通用以支持其他协议。

销毁 xx_text_input_manager 对象。

为给定 seat 创建新的文本输入对象。