# QmlInputMethod

**Repository Path**: xxz_code_space/QmlInputMethod

## Basic Information

- **Project Name**: QmlInputMethod
- **Description**: QML输入法及虚拟键盘API
- **Primary Language**: C++
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 9
- **Created**: 2023-12-15
- **Last Updated**: 2023-12-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QML输入法
本项目分为两个模块：中文输入法和虚拟键盘

其中输入法模块可单独使用，而虚拟键盘模块依赖输入法模块
## 输入法
### Introduction
QML输入法，过滤键盘事件，分割拼音并从数据库获取词组，处理后显示。
可根据词频调整候选词顺序，并可保存用户词。
### User manual
与一般PC输入法基本相同
- `Ctrl+回车键`切换中英文输入
- `减号`、`等号`键候选词上下翻页
- `空格键`、`数字键`、`鼠标`或`触屏`点击选词
- `回车键`直接输入当前文本
- `ESC键`取消本次输入
- `退格键`删除

*目前所有标点符号皆为半角符号，暂未实现中文全角标点符号功能*

### Usage

***仅支持`main.qml`文件为`ApplicationWindow`或其他有`activeFocusControl`属性的组件***

1. 将以下文件加入工程
    ```
    inputcore.h
    inputcore.cpp
    databaseoperator.h
    databaseoperator.cpp
    qmlhelp.h
    qmlhelp.cpp
    InputMethodViewer.qml
    InputField.qml
    CandidateBar.qml
    ```
2. 在主文件中定义函数`inputCoreInsteance`，并添加需要监听的对象类型名
    ```
    static QObject *inputCoreInstance(QQmlEngine *, QJSEngine * engine)
    {
        InputCore * ins = new InputCore(engine);
        ins->listenClassNameList << "QQuickTextField" << "QQuickTextArea";
        return ins;
    }
    ```
3. 在`main`函数中注册`InputCore`单例
    ```
    qmlRegisterSingletonType<InputCore>(
                "InputMethod", 1, 0,
                "Input", inputCoreInstance);
    ```

4. 在主qml文件的`ApplicationWindow`中添加`InputMethodViewer`组件，并调用`Input.setlistenRoot(object)`
    ```
    import InputMetod 1.0

    ApplicationWindow {
        //other component

        Component.onCompleted: Input.setlistenRoot(this)
        InputMethodViewer {

        }
    }
    ```
5. 将附件中的`chinese.db`加入可执行文件同一目录下

### C++ Class
- `InputCore`
    #### Function & Value
    `void setlistenRoot(QObject *object)`
    ：    设置根监听，object子组件中所有类名在listenClassNameList中的都会被监听

    `QStringList listenClassNameList`
    :    监听类名列表

    `void resetDatabase()`
    :    重置数据库，包含删除用户词和重置词频

    `int getMaxWordsNumber()` , `bool setMaxWordsNumber(int max)`
    :    最大汉字数量


### Qml Component


- `InputMethodViewer`
    ：    输入法界面组件，点击候选词或者输入序号进行选词，点击翻页按钮或`-`,`=`键翻页，自动根据activeFocusControl位置调整自身坐标

    #### Read and Write Property

    `int candidateWordsPerPage: 5`
    :    每页候选词数

    `int inputFontSize: 30`
    :    输入文字大小

    `int candidateFontSize: 30`
    :    候选词文字大小

    `int candidateWordsSpacing: 10`
    :    候选词间距

    `int margin: 10`
    :    输入文字及候选词边距

    `int candidateWordsStyle: Input.CandidateWords_Horizontal`
    :    候选词面板样式

            Input.CandidateWords_Horizontal //横版样式
            Input.CandidateWords_Vertical   //竖版样式，测试较少，可能存在某些问题
            
    `string inputColor: "DarkCyan"`
    :    输入文字颜色

    `string candidateWordsColor: "DarkCyan"`
    :    候选词文字颜色

    `string candidateFirstWordColor: "Red"`
    :    第一个候选词文字颜色

    `int maxY: 550`
    :    最大Y值，超过该值输入法将位于输入框上方

    **同时，`InputMethodViewer`继承自[`Rectangle`](https://doc-snapshots.qt.io/qt5-5.9/qml-qtquick-rectangle.html)，所以包括`color`、`border.color`等属性可直接修改**

    #### Read Only Property
    `real visible`
    :    可见性，可通过读取该属性判断输入法是否激活

    `real opacity`
    :    透明度，激活或关闭时会自动重置

    `real width`
    :    宽度，自适应

    `real height`
    :    高度，自适应

    `real x`
    :    x坐标，自适应

    `real y`
    :    y坐标，自适应

    `real objectX`
    :    输入对象x坐标


    #### Function
    `function call(activeFocusControl)`
    :    自动判断是否调用指示器




- `InputMethodIndicator`
    ：    输入法指示器，显示当前输入语言，点击切换输入语言，可拖动位置，并自动贴边
    #### Read and Write Property
    `int maxX: 1024`
    :    最大x值

    `int maxY: 600`
    :    最大Y值

    `int welt: 100`
    :    自动贴边阈值

    **同时，`InputMethodIndicator`继承自[`Rectangle`](https://doc-snapshots.qt.io/qt5-5.9/qml-qtquick-rectangle.html)，所以包括`color`、`border.color`等属性可直接修改**

    #### Read Only Property
    `bool chinese`
    :    是否中文，需要绑定InputMethod.chinese


## 虚拟键盘

### Introduction
QML虚拟键盘，发送键盘事件以实现输入

### User manual
与一般虚拟键盘基本相同
- `Ctrl+空格`或点击`中/En`按钮切换语言
- `鼠标`，`触屏`点击或`空格`按钮选词
- `分`按钮分词，英文时即为大写锁
- 长按按钮即输入其右上角符号
- `123`进入数字符号输入模式
- `回车`按钮实为`tab`键功能

*目前所有标点符号皆为半角符号，暂未实现全角标点符号功能*

### Usage
1. 完成上述输入法模块中`Usage`步骤
2. 在`main`函数中添加上下文属性`QmlHelper`对象
    ```
    QQmlApplicationEngine engine;
    QmlHelper qmlHelper;
    engine.rootContext()->setContextProperty("helper", &qmlHelper);
    ```
3. 将`VirtualKeyboard.qml`加入项目
4. 在主qml文件的`ApplicationWindow`中添加`VirtualKeyboard组件`，并调用函数及绑定参数
    ```
    import InputMetod 1.0

    ApplicationWindow {
        id: appWindow
        //other component
        Rectangle{
            id: root
        }

        Component.onCompleted: Input.setlistenRoot(this)
        InputMethodViewer {
            id: inputmethod
        }
        VirtualKeyboard {
            anchors.fill: parent
            chinese: inputmethod.chinese
            root: root
            window: appWindow
        }
        onActiveFocusControlChanged: {
            virtualKeyboard.item.call(activeFocusControl, 0)
        }
    }
    ```
### Qml Component

- `VirtualKeyboard`
    #### Read and Write Property
    `int keySpacing: 8`
    :    键之间的间隔

    `int keyButtonWidth: (width - keySpacing*11) / 10`
    :    键宽度，默认自适应

    `int keyButtonHeight: (keyboardHeight - keySpacing * 4) / 4`
    :    键高度，默认自适应

    `int keyTextFontSize: 30`
    :    键字体大小

    `int shiftKeyTextFontSize: 15`
    :    键右上角长按字体大小

    `int keyboardHeight: height / 2`
    :    虚拟键盘高度

    `string color: "AliceBlue"`
    :    虚拟键盘背景颜色

    `bool chinese`
    :    中英文，可以绑定inputmethod.chinese

    `var root`
    :    绑定需要抬升的根控件

    `var window`
    :    绑定窗口控件

    `int defaultRootY: 0`
    :    根控件默认Y坐标


    #### Read Only Property
    `bool active`
    :    虚拟键盘是否激活

    `bool capsLock`
    :    大写锁是否开启，暂时无法与物理键盘联动

    `bool shift`
    :    数字符号模式是否开启

    `bool raise`
    :    是否对根控件进行了抬升


    #### Function
    `call(activeFocusControl, offset)`
    :    调用虚拟键盘，建议在`ApplicationWindow`的`onActiveFocusControlChanged`槽中直接调用

            activeFocusControl  //输入对象
            offset              //遮挡判断微调
    #### Skills
    - 可通过`Loader`动态加载`VirtualKeyboard`，具体参考`main.qml`