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 使用模式识别模式::无 |
QVirtualKeyboardInputEngine::PatternRecognitionMode::Handwriting | 1 | 手写识别的模式识别。 |
QVirtualKeyboardInputEngine::PatternRecognitionMode::HandwritingRecoginition | Handwriting | obsolete 使用模式识别模式::手写 |
枚举类 QVirtualKeyboardInputEngine::ReselectFlag
flags QVirtualKeyboardInputEngine::ReselectFlags
此枚举指定了重新选择字词的规则。
| 常量 | 值 | 说明 |
|---|---|---|
QVirtualKeyboardInputEngine::ReselectFlag::WordBeforeCursor | 0x1 | 激活光标前的字。专门使用该标志时，单词必须在光标处结束。 |
QVirtualKeyboardInputEngine::ReselectFlag::WordAfterCursor | 0x2 | 激活光标后的字。专用此标记时，单词必须在光标处准确开始。 |
QVirtualKeyboardInputEngine::ReselectFlag::WordAtCursor | WordBeforeCursor | WordAfterCursor | 在光标处激活单词。该标记是上述标记的组合，但单词不能在光标处开始或停止。 |
ReselectFlags 类型是QFlags<ReselectFlag> 的类型定义。它存储 ReselectFlag 值的 OR 组合。
enum class QVirtualKeyboardInputEngine::TextCase
该枚举用于指定输入法的文本大小写。
| 常量 | 值 | 说明 |
|---|---|---|
QVirtualKeyboardInputEngine::TextCase::Lower | 0 | 小写文本。 |
QVirtualKeyboardInputEngine::TextCase::Upper | 1 | 大写文本 |
属性文档
[read-only] activeKey : const 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) |
Notifier 信号：
| void | inputModeChanged() |
[read-only] inputModes : const QList<int>
该属性包含活动输入法的可用输入模式。
可用输入模式列表取决于输入法和本地语言。当任何一个依赖项发生变化时，此属性都会更新。
访问功能：
| QList<int> | inputModes() const |
通知信号：
| void | inputModesChanged() |
[read-only, since QtQuick.VirtualKeyboard 2.0] patternRecognitionModes : const QList<int>
该属性包含可用模式识别模式列表。
可用模式识别模式列表。
该属性在 QtQuick.VirtualKeyboard 2.0 中引入。
访问功能：
| QList<int> | patternRecognitionModes() const |
Notifier 信号：
[read-only] previousKey : const Qt::Key
该属性保存上一个活动键。
之前按下的键。
访问功能：
| Qt::Key | previousKey() const |
通知信号：
| void | previousKeyChanged(Qt::Key key) |
[read-only] wordCandidateListModel : QVirtualKeyboardSelectionListModel* const
候选词列表的列表模型。
使用此属性可访问候选词列表的列表模型。
访问功能：
| QVirtualKeyboardSelectionListModel * | wordCandidateListModel() const |
通知信号：
| void | wordCandidateListModelChanged() |
[read-only] wordCandidateListVisibleHint : const bool
候选词列表的可见提示。
使用此属性可检查候选词列表是否应在用户界面中可见。
访问功能：
| bool | wordCandidateListVisibleHint() const |
Notifier 信号：
| 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 。
注： 属性 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 提供有关屏幕上下文的信息。
根据定义，在调用traceEnd() 方法之前，QVirtualKeyboardTrace 对象一直有效。
跟踪交互通过调用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)
表示通过给定的text 和modifiers 点击了虚拟key 。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 。
© 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.
