#  图形界面开发

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# Qt 图形页面开发

## 文档概述

本文档介绍如何在 Quectel Pi M1 的 Debian 系统中搭建 Qt6 图形界面开发环境，并创建、编译和运行一个基于 Qt Quick/QML 的示例程序。

## 环境准备

```bash
sudo apt update
sudo apt install -y build-essential cmake ninja-build qt6-base-dev qt6-base-dev-tools qt6-declarative-dev qt6-declarative-dev-tools qt6-wayland
```

## 创建工程

本示例工程包含以下三个源码文件：

- main.cpp（程序入口文件）

- Main.qml（Qt Quick 图形界面）

- CMakeLists.txt（CMake 工程配置文件）

### 创建 main.cpp

文件内容：

```cpp
#include <QGuiApplication>
#include <QQmlApplicationEngine>
int main(int argc, char *argv[]){
    QGuiApplication app(argc, argv);

    QQmlApplicationEngine engine;
    engine.loadFromModule("QtQuectelDemo", "Main");

    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}
```

### 创建 Main.qml

文件内容：

```plaintext
import QtQuick
import QtQuick.Controls

ApplicationWindow {
    width: 640height: 480visible: truetitle: "Qt Quectel Demo"Column {
        anchors.centerIn: parentspacing: 20Text {
            id: labeltext: "Hello Quectel Pi M1!"font.pixelSize: 28
        }

        Button {
            text: "Click Me"onClicked: {
                label.text = "Qt Demo Running!"
            }
        }
    }
}
```

### 创建 CMakeLists.txt

文件内容：

```cmake
cmake_minimum_required(VERSION 3.16)

project(QtQuectelDemo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 REQUIRED COMPONENTS Quick QuickControls2)

qt_standard_project_setup(REQUIRES 6.8)

qt_add_executable(appQtQuectelDemo
    main.cpp
)

qt_add_qml_module(appQtQuectelDemo
    URI QtQuectelDemo
    VERSION 1.0
    QML_FILES
        Main.qml
)

target_link_libraries(appQtQuectelDemo
    PRIVATE
        Qt6::Quick
        Qt6::QuickControls2
)

install(TARGETS appQtQuectelDemo
    BUNDLE DESTINATION .
    RUNTIME DESTINATION bin
)
```

## 编译工程

在源码目录执行：

```bash
mkdir -p build
cd build
cmake -G Ninja ..
ninja
```

生成可以执行文件appQtQuectelDemo。

## 运行程序

（1）在gnome终端里执行：./appQuQuectelDemo

```{image} images/image_RZFNbwLYXosVw0xiD9PcemKcnZg.webp
:width: 1280px
:height: 800px
:align: center
```

（2）在ssh或者adb的连接下运行程序

```plaintext
export XDG_RUNTIME_DIR=/run/user/1007
export WAYLAND_DISPLAY=wayland-0
export QT_QPA_PLATFORM=wayland
./appQtQuectelDemo
```

## 运行效果

程序启动后将显示 Qt 图形界面窗口。

```{image} images/image_PfjNbFfwhoOwwfxchxncxXPRn7g.webp
:width: 1280px
:height: 800px
:align: center
```

```{image} images/image_NSTcb4ipAorJ4KxMBv3cNYzmnDb.webp
:width: 1280px
:height: 800px
:align: center
```

# wxWidgets 图形界面开发

## 文档概述

本文档介绍如何在 Quectel Pi M1 的 Debian 系统中搭建 wxWidgets 图形界面开发环境，并创建、编译和运行一个基于 wxWidgets 的示例程序。

## 环境准备

```bash
sudo apt update
sudo apt install -y build-essential cmake ninja-build libwxgtk3.2-dev libgtk-3-0
```

## 创建工程

### 创建 main.cpp

文件内容

```cpp
#include <wx/wx.h>
class QuectelFrame : public wxFrame
{
public:
    QuectelFrame()
        : wxFrame(nullptr,
                  wxID_ANY,
                  "wxWidgets Quectel Demo",
                  wxDefaultPosition,
                  wxSize(640, 480))
    {
        wxPanel *panel = new wxPanel(this);
        wxBoxSizer *mainSizer = new wxBoxSizer(wxVERTICAL);

        statusText = new wxStaticText(
            panel,
            wxID_ANY,
            "Hello Quectel Pi M1!"
        );

        wxFont font = statusText->GetFont();
        font.SetPointSize(20);
        statusText->SetFont(font);

        wxButton *button = new wxButton(
            panel,
            wxID_ANY,
            "Click Me"
        );

        mainSizer->AddStretchSpacer();
        mainSizer->Add(statusText, 0, wxALIGN_CENTER | wxALL, 10);
        mainSizer->Add(button, 0, wxALIGN_CENTER | wxALL, 10);
        mainSizer->AddStretchSpacer();

        panel->SetSizer(mainSizer);

        button->Bind(
            wxEVT_BUTTON,
            &QuectelFrame::OnButtonClick,
            this
        );

        Centre();
    }

private:
    wxStaticText *statusText;

    void OnButtonClick(wxCommandEvent &event){
        statusText->SetLabel("wxWidgets Demo Running!");
    }
};

class QuectelApp : public wxApp
{
public:
    bool OnInit() override{
        QuectelFrame *frame = new QuectelFrame();
        frame->Show(true);
        return true;
    }
};

wxIMPLEMENT_APP(QuectelApp);
```

### 创建 CMakeLists.txt

文件内容

```cmake
cmake_minimum_required(VERSION 3.16)

project(WxQuectelDemo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(wxWidgets REQUIRED COMPONENTS core base)

include(${wxWidgets_USE_FILE})

add_executable(appWxQuectelDemo
    main.cpp
)

target_link_libraries(appWxQuectelDemo
    PRIVATE
        ${wxWidgets_LIBRARIES}
)
```

## 编译工程

在源码目录执行：

```bash
mkdir -p build
cd build
cmake -G Ninja ..
ninja
```

## 运行程序

./appWxQuectelDemo

```{image} images/image_I43cbKQY9oJBVCxGHaEc5nEznme.webp
:width: 1280px
:height: 800px
:align: center
```

## 运行效果

程序启动后将显示 wx 图形界面窗口。

```{image} images/image_Nxe4blm5eoIimvxv7bPcoXwSn2d.webp
:width: 1280px
:height: 800px
:align: center
```

```{image} images/image_VWJub58FWov9FJxmTQycFnWZn3g.webp
:width: 1280px
:height: 800px
:align: center
```

# Weston 环境下 Qt 图形应用

前文已经完成 Qt 开发环境安装、工程创建及编译，生成可执行程序：appQtQuectelDemo

## 切换 Weston 桌面：

```plaintext
qpi-config switch weston
reboot
```

## 配置 Weston Wayland 环境

```javascript
cd /home/pi/QtQuectelDemo/build
export XDG_RUNTIME_DIR=/run/user/root
export WAYLAND_DISPLAY=wayland-1
export QT_QPA_PLATFORM=wayland
export QT_WAYLAND_SHELL_INTEGRATION=wl-shell
export QT_QUICK_BACKEND=software
```

## 运行 Qt 程序

```plaintext
./appQtQuectelDemo
```

## 运行效果

```{image} images/image_BbQMb5PKRocn9GxSmBuczJGMnIh.webp
:width: 1586px
:height: 992px
:align: center
```

```{image} images/image_CUrZbSNoxoMzQBx0rTucibk4nvh.webp
:width: 1586px
:height: 992px
:align: center
```

# Weston 环境下 wxWidgets 兼容性验证

Weston 环境下 wxWidgets 存在 Wayland 兼容性问题，功能暂未验证通过。