QVirtualKeyboardInputEngine Class
InputEngine 类提供了一个支持C++和QML集成的输入引擎。更多内容...
| 标题： | #include <QVirtualKeyboardInputEngine> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS VirtualKeyboard) target_link_libraries(mytarget PRIVATE Qt6::VirtualKeyboard) |
| qmake： | QT += virtualkeyboard |
| 在 QML 中： | InputEngine |
| 继承自： | QObject |
公共类型
| enum class | InputMode { Latin, Numeric, Dialable, Pinyin, Cangjie, …, HiraganaFlick } |
| enum class | PatternRecognitionMode { None, PatternRecognitionDisabled, Handwriting, HandwritingRecoginition } |
| enum class | ReselectFlag { WordBeforeCursor, WordAfterCursor, WordAtCursor } |
| flags | ReselectFlags |
| enum class | TextCase { Lower, Upper } |
属性
|
|
公共函数
| Qt::Key | activeKey() const |
| QVirtualKeyboardInputContext * | inputContext() const |
| QVirtualKeyboardAbstractInputMethod * | inputMethod() const |
| QVirtualKeyboardInputEngine::InputMode | inputMode() const |
| QList<int> | inputModes() const |
| QList<int> | patternRecognitionModes() const |
| Qt::Key | previousKey() const |
(since QtQuick.VirtualKeyboard 2.0) bool | reselect(int cursorPosition, const QVirtualKeyboardInputEngine::ReselectFlags &reselectFlags) |
| void | setInputMethod(QVirtualKeyboardAbstractInputMethod *inputMethod) |
| void | setInputMode(QVirtualKeyboardInputEngine::InputMode inputMode) |
(since QtQuick.VirtualKeyboard 2.0) QVirtualKeyboardTrace * | traceBegin(int traceId, QVirtualKeyboardInputEngine::PatternRecognitionMode patternRecognitionMode, const QVariantMap &traceCaptureDeviceInfo, const QVariantMap &traceScreenInfo) |
| bool | traceEnd(QVirtualKeyboardTrace *trace) |
| void | virtualKeyCancel() |
| bool | virtualKeyClick(Qt::Key key, const QString &text, Qt::KeyboardModifiers modifiers) |
| bool | virtualKeyPress(Qt::Key key, const QString &text, Qt::KeyboardModifiers modifiers, bool repeat) |
| bool | virtualKeyRelease(Qt::Key key, const QString &text, Qt::KeyboardModifiers modifiers) |
| QVirtualKeyboardSelectionListModel * | wordCandidateListModel() const |
| bool | wordCandidateListVisibleHint() const |
信号
| void | activeKeyChanged(Qt::Key key) |
| void | inputMethodChanged() |
| void | inputMethodReset() |
| void | inputMethodUpdate() |
| void | inputModeChanged() |
| void | inputModesChanged() |
(since QtQuick.VirtualKeyboard 2.0) void | patternRecognitionModesChanged() |
| void | previousKeyChanged(Qt::Key key) |
| void | virtualKeyClicked(Qt::Key key, const QString &text, Qt::KeyboardModifiers modifiers, bool isAutoRepeat) |
| void | wordCandidateListModelChanged() |
| void | wordCandidateListVisibleHintChanged() |
成员类型文档
enum class QVirtualKeyboardInputEngine::InputMode
此枚举用于指定输入法的输入模式。
| 常量 | 值 | 描述 |
|---|---|---|
QVirtualKeyboardInputEngine::InputMode::Latin | 0 | 拉丁文的默认输入模式。 |
QVirtualKeyboardInputEngine::InputMode::Numeric | 1 | 只允许数字输入。 |
QVirtualKeyboardInputEngine::InputMode::Dialable | 2 | 仅允许拨号输入。 |
QVirtualKeyboardInputEngine::InputMode::Pinyin | 3 | 中文拼音输入法。 |
QVirtualKeyboardInputEngine::InputMode::Cangjie | 4 | 中文的仓颉输入法。 |
QVirtualKeyboardInputEngine::InputMode::Zhuyin | 5 | 中文注音输入法。 |
QVirtualKeyboardInputEngine::InputMode::Hangul | 6 | 韩语的韩文输入法。 |
QVirtualKeyboardInputEngine::InputMode::Hiragana | 7 | 日语的平假名输入法。 |
QVirtualKeyboardInputEngine::InputMode::Katakana | 8 | 日语的片假名输入法。 |
QVirtualKeyboardInputEngine::InputMode::FullwidthLatin | 9 | 东亚语言的全角拉丁输入法。 |
QVirtualKeyboardInputEngine::InputMode::Greek | 10 | 希腊语输入模式。 |
QVirtualKeyboardInputEngine::InputMode::Cyrillic | 11 | 西里尔字母输入模式。 |
QVirtualKeyboardInputEngine::InputMode::Arabic | 12 | 阿拉伯语输入模式。 |
QVirtualKeyboardInputEngine::InputMode::Hebrew | 13 | 希伯来语输入模式。 |
QVirtualKeyboardInputEngine::InputMode::ChineseHandwriting | 14 | 中文手写输入模式。 |
QVirtualKeyboardInputEngine::InputMode::JapaneseHandwriting | 15 | 日语手写输入模式。 |
QVirtualKeyboardInputEngine::InputMode::KoreanHandwriting | 16 | 韩语手写输入模式。 |
QVirtualKeyboardInputEngine::InputMode::Thai | 17 | 泰语输入模式。 |
QVirtualKeyboardInputEngine::InputMode::Stroke | 18 | 中文笔画输入模式。 |
QVirtualKeyboardInputEngine::InputMode::Romaji | 19 | 日语罗马字输入模式。 |
QVirtualKeyboardInputEngine::InputMode::HiraganaFlick | 20 | 日语的滑动输入模式。 |
enum class QVirtualKeyboardInputEngine::PatternRecognitionMode
此枚举用于指定输入法的输入模式。
| 常量 | 值 | 描述 |
|---|---|---|
QVirtualKeyboardInputEngine::PatternRecognitionMode::None | 0 | 不支持模式识别。 |
QVirtualKeyboardInputEngine::PatternRecognitionMode::PatternRecognitionDisabled | None | obsolete 使用 PatternRecognitionMode::None |
QVirtualKeyboardInputEngine::PatternRecognitionMode::Handwriting | 1 | 手写识别的模式识别模式。 |
QVirtualKeyboardInputEngine::PatternRecognitionMode::HandwritingRecoginition | Handwriting | obsolete 使用 PatternRecognitionMode::Handwriting |
enum class QVirtualKeyboardInputEngine::ReselectFlag
flags QVirtualKeyboardInputEngine::ReselectFlags
此枚举指定了单词重新选择的规则。
| 常量 | 值 | 描述 |
|---|---|---|
QVirtualKeyboardInputEngine::ReselectFlag::WordBeforeCursor | 0x1 | 激活光标前面的单词。当仅使用此标志时，该单词必须正好以光标处结束。 |
QVirtualKeyboardInputEngine::ReselectFlag::WordAfterCursor | 0x2 | 激活光标后面的单词。当仅使用此标志时，该单词必须正好从光标处开始。 |
QVirtualKeyboardInputEngine::ReselectFlag::WordAtCursor | WordBeforeCursor | WordAfterCursor | 激活光标所在位置的单词。此标志是上述标志的组合，但单词不能从光标处开始或结束。 |
ReselectFlags 类型是QFlags<ReselectFlag> 的 typedef。它存储 ReselectFlag 值的按“或”运算组合。
enum class QVirtualKeyboardInputEngine::TextCase
此枚举用于指定输入法中的文本大小写形式。
| 常量 | 值 | 描述 |
|---|---|---|
QVirtualKeyboardInputEngine::TextCase::Lower | 0 | 小写文本。 |
QVirtualKeyboardInputEngine::TextCase::Upper | 1 | 大写文本。 |
属性文档
[read-only] activeKey : Qt::Key
该属性保存当前按下的键。
当前按下的键。
访问函数：
| Qt::Key | activeKey() const |
通知信号：
| void | activeKeyChanged(Qt::Key key) |
inputMethod : QVirtualKeyboardAbstractInputMethod*
该属性保存当前活动的输入法。
使用此属性可将输入法设为活动状态，或监听活动输入法的变更。
访问函数：
| QVirtualKeyboardAbstractInputMethod * | inputMethod() const |
| void | setInputMethod(QVirtualKeyboardAbstractInputMethod *inputMethod) |
通知信号：
| void | inputMethodChanged() |
inputMode : InputMode
该属性存储当前的输入模式。
使用此属性可获取或设置当前输入模式。InputEngine::inputModes 提供当前输入法和区域设置下有效的输入模式列表。
访问函数：
| QVirtualKeyboardInputEngine::InputMode | inputMode() const |
| void | setInputMode(QVirtualKeyboardInputEngine::InputMode inputMode) |
通知信号：
| void | inputModeChanged() |
[read-only] inputModes : QList<int>
该属性存储了当前活动输入法可用的输入模式。
可用输入模式的列表取决于输入法和区域设置。当其中任何一个依赖项发生变化时，该属性都会更新。
访问函数：
| QList<int> | inputModes() const |
通知信号：
| void | inputModesChanged() |
[read-only, since QtQuick.VirtualKeyboard 2.0] patternRecognitionModes : QList<int>
该属性包含可用模式识别模式的列表。
可用模式识别模式的列表。
该枚举在 QtQuick.VirtualKeyboard 2.0 中引入。
访问函数：
| QList<int> | patternRecognitionModes() const |
通知器信号：
[read-only] previousKey : Qt::Key
该属性保存上一次按下的有效键。
先前按下的键。
访问函数：
| Qt::Key | previousKey() const |
通知信号：
| void | previousKeyChanged(Qt::Key key) |
[read-only] wordCandidateListModel : QVirtualKeyboardSelectionListModel*
单词候选项列表的列表模型。
使用此属性可访问单词候选项列表的列表模型。
访问函数：
| QVirtualKeyboardSelectionListModel * | wordCandidateListModel() const |
通知器信号：
| void | wordCandidateListModelChanged() |
[read-only] wordCandidateListVisibleHint : bool
单词候选项列表的可见提示。
使用此属性可控制词汇候选列表在用户界面中是否显示。
访问函数：
| bool | wordCandidateListVisibleHint() const |
通知器信号：
| void | wordCandidateListVisibleHintChanged() |
成员函数文档
Qt::Key QVirtualKeyboardInputEngine::activeKey() const
返回当前活动的键；如果没有活动键，则返回Qt::Key_unknown 。
注意： 这是 activeKey 属性的获取器 函数。
[signal] void QVirtualKeyboardInputEngine::activeKeyChanged(Qt::Key key)
表示活动key 已发生变化。
注意： 这是属性activeKey的通知 信号。
QVirtualKeyboardInputContext *QVirtualKeyboardInputEngine::inputContext() const
返回与该输入引擎关联的InputContext 实例。
QVirtualKeyboardAbstractInputMethod *QVirtualKeyboardInputEngine::inputMethod() const
返回当前活动的输入法。
注意： 这是 inputMethod 属性的获取器函数 。
另请参阅 ` setInputMethod()`。
[signal] void QVirtualKeyboardInputEngine::inputMethodChanged()
表示输入法已发生变化。
注意： 这是属性inputMethod的通知器 信号。
[signal] void QVirtualKeyboardInputEngine::inputMethodReset()
当需要重置输入法时触发此信号。
注意： 当输入法被激活时，该 信号会自动连接到QVirtualKeyboardAbstractInputMethod::reset()和InputMethod::reset()方法。
[signal] void QVirtualKeyboardInputEngine::inputMethodUpdate()
注意： 当输入法激活时，该 信号会自动连接到QVirtualKeyboardAbstractInputMethod::update() 和InputMethod::update()。
[signal] void QVirtualKeyboardInputEngine::inputModeChanged()
表示输入模式已发生变化。
注意： 这是属性inputMode的通知器 信号。
QList<int> QVirtualKeyboardInputEngine::inputModes() const
返回可用输入模式的列表。
注意： 这是属性 inputModes 的获取 函数。
[signal] void QVirtualKeyboardInputEngine::inputModesChanged()
表示可用的输入模式已发生变化。
注意： 这是属性inputModes的通知器 信号。
QList<int> QVirtualKeyboardInputEngine::patternRecognitionModes() const
返回支持的模式识别模式列表。
注意： 这是属性 patternRecognitionModes 的获取函数 。
[signal, since QtQuick.VirtualKeyboard 2.0] void QVirtualKeyboardInputEngine::patternRecognitionModesChanged()
表示可用的模式识别模式已发生变化。
注意： 这是属性patternRecognitionModes的通知 信号。
此功能自 QtQuick.VirtualKeyboard 2.0 起引入。
Qt::Key QVirtualKeyboardInputEngine::previousKey() const
返回之前处于活动状态的键；如果尚未有键处于活动状态，则返回Qt::Key_unknown 。
注意： 这是 property previousKey 的获取 函数。
[signal] void QVirtualKeyboardInputEngine::previousKeyChanged(Qt::Key key)
表示之前的key 已发生变化。
注意： 这是属性previousKey的通知 信号。
[invokable, since QtQuick.VirtualKeyboard 2.0] bool QVirtualKeyboardInputEngine::reselect(int cursorPosition, const QVirtualKeyboardInputEngine::ReselectFlags &reselectFlags)
该函数尝试重新选中位于cursorPosition 处的单词。reselectFlags 定义了根据光标位置选中该单词的规则。
如果单词被成功重新选中，该函数将返回true 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
该函数在 QtQuick.VirtualKeyboard 2.0 中引入。
void QVirtualKeyboardInputEngine::setInputMethod(QVirtualKeyboardAbstractInputMethod *inputMethod)
将inputMethod 设置为当前输入法。
注意： 这是属性inputMethod 的设置器 函数。
另请参阅 inputMethod()。
[invokable, since QtQuick.VirtualKeyboard 2.0] QVirtualKeyboardTrace *QVirtualKeyboardInputEngine::traceBegin(int traceId, QVirtualKeyboardInputEngine::PatternRecognitionMode patternRecognitionMode, const QVariantMap &traceCaptureDeviceInfo, const QVariantMap &traceScreenInfo)
启动与输入引擎的跟踪交互。
该跟踪通过traceId 进行唯一标识。如果输入法接受该事件，输入引擎将把该ID分配给QVirtualKeyboardTrace 对象。
patternRecognitionMode 指定了用于该模式的识别模式。
如果当前输入法接受该事件，则返回一个与该交互关联的QVirtualKeyboardTrace 对象。如果输入法忽略该事件，则返回NULL值。
traceCaptureDeviceInfo 提供有关源设备的信息，而traceScreenInfo 提供有关屏幕上下文的信息。
根据定义，QVirtualKeyboardTrace 对象在调用traceEnd() 方法之前一直有效。
调用traceEnd() 方法将结束跟踪交互。
注意： 可以通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
该函数在 QtQuick.VirtualKeyboard 2.0 中引入。
[invokable] bool QVirtualKeyboardInputEngine::traceEnd(QVirtualKeyboardTrace *trace)
终止与输入引擎的跟踪交互。
调用此函数后，trace 对象可在任何时候被丢弃。
如果跟踪交互已被接受（即触摸事件不应用于其他任何用途），则该函数返回 true。
注意： 可通过元对象系统和从 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] void QVirtualKeyboardInputEngine::virtualKeyCancel()
将活动键的状态恢复原状，同时不触发键盘事件。当用户取消当前键操作且需要恢复键状态时，此方法非常有用。
注意：此 函数可通过元对象系统和 QML 调用。请参阅Q_INVOKABLE 。
[invokable] bool QVirtualKeyboardInputEngine::virtualKeyClick(Qt::Key key, const QString &text, Qt::KeyboardModifiers modifiers)
为给定的key 、text 和modifiers 触发键盘点击事件。如果键盘事件被输入引擎接受，则返回true 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[signal] void QVirtualKeyboardInputEngine::virtualKeyClicked(Qt::Key key, const QString &text, Qt::KeyboardModifiers modifiers, bool isAutoRepeat)
表示已点击虚拟key ，其text 和modifiers 分别为给定的值。isAutoRepeat 表示在按键被按下期间该事件是否会自动重复。该信号在输入法处理完按键事件后发出。
[invokable] bool QVirtualKeyboardInputEngine::virtualKeyPress(Qt::Key key, const QString &text, Qt::KeyboardModifiers modifiers, bool repeat)
由键盘层调用，用于指示key 被按下，并提供text 和modifiers 参数。
key 被设置为活动键（按下键）。当通过virtualKeyRelease() 方法释放该键时，会触发实际的键盘事件。可通过调用virtualKeyCancel() 来取消该按键事件。
如果repeat 的值为true ，则按键操作还会启动按键重复定时器。
如果该键被此输入引擎接受，则返回true 。
注意： 可以通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
另请参阅 virtualKeyCancel() 和virtualKeyRelease()。
[invokable] bool QVirtualKeyboardInputEngine::virtualKeyRelease(Qt::Key key, const QString &text, Qt::KeyboardModifiers modifiers)
在key 处释放键。如果该事件并非由循环定时器触发，则该方法会为输入法触发一个键事件。text 和modifiers 将传递给输入法。
如果键被输入引擎接受，则返回true 。
注意：此 函数可通过元对象系统以及从 QML 中调用。参见Q_INVOKABLE 。
© 2026 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.
