Back to Qt.io
Contact Us Blog Download Qt

QInputMethodEvent Class

QInputMethodEvent 类为输入法事件提供参数。更多

头文件： #include <QInputMethodEvent>
CMake： find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake： QT += gui
继承： QEvent

公共类型

class Attribute
enum AttributeType { TextFormat, Cursor, Language, Ruby, Selection }

公共函数

QInputMethodEvent()
QInputMethodEvent(const QString &preeditText, const QList<QInputMethodEvent::Attribute> &attributes)
const QList<QInputMethodEvent::Attribute> &attributes() const
const QString &commitString() const
const QString &preeditString() const
int replacementLength() const
int replacementStart() const
void setCommitString(const QString &commitString, int replaceFrom = 0, int replaceLength = 0)

详细说明

当使用输入法在部件中输入文本时，输入法事件会被发送到部件。输入法广泛用于在非拉丁字母语言中输入文本。

请注意，在创建自定义文本编辑部件时，必须明确设置Qt::WA_InputMethodEnabled window 属性（使用QWidget::setAttribute() 函数），才能接收输入法事件。

键盘输入 widget 的作者希望能正确处理具有复杂字符输入的语言，因此他们对这些事件很感兴趣。此类语言的文本输入通常需要三个步骤：

  1. 开始组合

    当用户按下键盘上的第一个键时，就会创建一个输入上下文。该输入上下文将包含一串输入的字符。

  2. 合成

    每按下一个新键，输入法都会尝试创建一个与迄今键入的文本相匹配的字符串，称为预编辑字符串。当输入上下文处于活动状态时，用户只能在属于该输入上下文的字符串内移动光标。

  3. 完成

    在某一时刻，用户会激活一个用户界面组件（也许是使用某个特定按键），在该组件中，用户可以从一系列与迄今键入的文本相匹配的字符串中进行选择。用户既可以确认选择，也可以取消输入；无论哪种情况，输入上下文都将关闭。

QInputMethodEvent 对这三个阶段进行建模，并传输正确呈现中间结果所需的信息。QInputMethodEvent 有两个主要参数：preeditString() 和commitString() 。preeditString() 参数给出当前活动的预编辑字符串。commitString() 参数给出的文本应添加到编辑器部件的文本中（或替换其中的部分内容）。它通常是输入操作的结果，必须直接插入到预编辑字符串之前的 widget 文本中。

如果commitString() 要替换编辑器中的部分文本，replacementLength() 将包含要替换的字符数。replacementStart() 包含从预编辑字符串起始位置开始替换字符的位置。

一些属性控制预编辑字符串的视觉外观（预编辑字符串以外文本的视觉外观仅由 widget 控制）。AttributeType 枚举描述了可以设置的不同属性。

实现QWidget::inputMethodEvent() 或QGraphicsItem::inputMethodEvent() 的类至少应理解并尊重TextFormat 和Cursor 属性。

由于输入方法需要能够查询部件或图形项的某些属性，因此子类还必须分别实现QWidget::inputMethodQuery() 和QGraphicsItem::inputMethodQuery() 。

当接收到输入法事件时，文本 widget 必须执行以下步骤：

  1. 如果 widget 有选定文本，则应删除选定文本。
  2. 删除从replacementStart() 开始的长度为replacementLength() 的文本，并用commitString() 代替。如果replacementLength() 为 0，replacementStart() 将给出commitString() 的插入位置。

    在进行替换时，预编辑字符串的区域会被忽略，因此从 -1 开始、长度为 2 的替换将删除预编辑字符串之前的最后一个字符和之后的第一个字符，并直接在预编辑字符串之前插入提交字符串。

    如果 widget 实现了撤消/重做，该操作将被添加到撤消堆栈中。

  3. 如果当前没有预编辑字符串，则在当前光标位置插入preeditString() ；否则就用从该事件接收到的字符串替换之前的preeditString 。

    如果 widget 实现了撤消/重做，则preeditString() 不应以任何方式影响撤消/重做堆栈。

    部件应检查要应用于预编辑字符串的属性列表。它必须至少理解TextFormat 和光标属性，并按照指定的方式呈现它们。

另请参阅 QInputMethod 。

成员类型文档

enum QInputMethodEvent::AttributeType

常数值说明
QInputMethodEvent::TextFormat0由 start 和 length 指定的预编辑字符串部分的QTextCharFormat 。value 包含类型为QTextFormat 的QVariant ，指定预编辑字符串这一部分的呈现方式。预编辑字符串的每一部分最多只能有一种格式。如果为字符串中的任何字符指定了多个格式，则其行为将是未定义的。符合要求的实现必须至少尊重格式的背景颜色、文本颜色和字体下划线属性。
QInputMethodEvent::Cursor1如果设置了光标，则应在预编辑字符串的起始位置显示光标。长度变量决定光标是否可见。如果长度为 0，则光标不可见。如果 value 是QVariant 类型的QColor ，则使用该颜色渲染游标，否则将使用周围文本的颜色。每个事件最多只能有一个光标属性。如果指定了多个光标属性，其行为将是未定义的。
QInputMethodEvent::Language2变体包含一个QLocale 对象，用于指定预编辑字符串特定部分的语言。预编辑字符串的每一部分最多只能设置一种语言。如果为字符串中的任何字符指定了几种语言，其行为将是未定义的。
QInputMethodEvent::Ruby3预编辑字符串部分的 ruby 文本。预编辑字符串的每一部分最多只能有一个 ruby 文本集。如果为字符串中的任何字符指定了多个 ruby 文本，其行为将是未定义的。
QInputMethodEvent::Selection4如果设置了该属性，编辑光标应移动到编辑器文本内容中的指定位置。与Cursor 不同的是，该属性不适用于编辑前文本，而是周围的文本。光标将在提交字符串后移动，而预编辑字符串将位于新的编辑位置。起始位置指定了新的位置，长度变量可用于设置从该位置开始的选择。该值未被使用。

另请参阅 Attribute 。

成员函数文档

QInputMethodEvent::QInputMethodEvent()

构造QEvent::InputMethod 类型的事件。attributes(),preeditString(),commitString(),replacementStart() 和replacementLength() 被初始化为默认值。

另请参阅 setCommitString()。

QInputMethodEvent::QInputMethodEvent(const QString &preeditText, const QList<QInputMethodEvent::Attribute> &attributes)

构造一个类型为QEvent::InputMethod 的事件。预编辑文本设置为preeditText ，属性设置为attributes 。

可使用setCommitString() 设置commitString()、replacementStart() 和replacementLength() 值。

另请参阅 preeditString() 和attributes()。

const QList<QInputMethodEvent::Attribute> &QInputMethodEvent::attributes() const

返回传递给QInputMethodEvent 构造函数的属性列表。属性控制预编辑字符串的视觉外观（预编辑字符串以外文本的视觉外观仅由 widget 控制）。

另请参阅 preeditString() 和Attribute 。

const QString &QInputMethodEvent::commitString() const

返回应添加（或替换）到编辑器 widget 文本中的文本。它通常是输入操作的结果，必须直接插入到 widget 文本的预编辑字符串之前。

另请参阅 setCommitString()、preeditString()、replacementStart() 和replacementLength()。

const QString &QInputMethodEvent::preeditString() const

返回编辑前的文本，即用户开始编辑前的文本。

另请参阅 commitString() 和attributes()。

int QInputMethodEvent::replacementLength() const

返回预编辑字符串中要替换的字符数。

另请参阅 replacementStart() 和setCommitString()。

int QInputMethodEvent::replacementStart() const

返回要替换的字符相对于预编辑字符串起始位置的位置。

另请参阅 replacementLength() 和setCommitString()。

void QInputMethodEvent::setCommitString(const QString &commitString, int replaceFrom = 0, int replaceLength = 0)

将提交字符串设置为commitString 。

提交字符串是应添加到（或替换）编辑器 widget 文本中的文本。它通常是输入操作的结果，必须直接插入到 widget 文本的预编辑字符串之前。

如果提交字符串要替换编辑器中的部分文本，replaceLength 指定要替换的字符数。replaceFrom 指定要替换的字符相对于预编辑字符串起始位置的位置。

另请参阅 commitString()、replacementStart() 和replacementLength()。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.