【入门级图文教程】Linux系统下在Qt Creator中创建自定义控件并在其他项目中引用

目录

本教程使用到的相关软件或产品：

教程正文：

        创建自定义控件：

        向Qt Creator添加插件：

        在其他项目中引用自定义控件：

        在使用qmake的项目中引用自定义控件：

        方式一 —— 添加外部库（推荐）

        方式二 —— pri 项目整体移植

        在使用Cmake的项目中引用自定义控件：

---

本教程使用到的相关软件或产品：

1. 版本    Windows 10 专业版
   版本号    22H2
   操作系统内部版本    19045.2486

   

2. 产品    VMware® Workstation 17 Pro
   版本    17.0.0 build-20800274

   

3. Ubuntu 20.04.5 LTS（LTS = Long Term Support意为长期支持版本）

   

4. Qt 5.15.2 (GCC 7.3.1 20180303 (Red Hat 7.3.1-5), 64 bit)
5. Qt Creator 5.0.0

   

教程正文：

---

        创建自定义控件：

打开Qt Creator，选择“新建文件或项目(N)”

在打开的对话框中选中“项目”分类下的“其他项目”下的“Qt 4设计师自定义控件”：

选择后开始进入项目配置环节，选择自己心仪的项目名称和路径，点击“下一步(N)”：

接下来选择构建套件(Kit)，按默认即可，点击“下一步(N)”：

接着指定自定义控件列表及属性，这里我们需要拟定“控件类(C)”的全英文名称（注意！名称必须以大写字母开头）：

        这里简要说一下图标文件，如果选择了一个图标文件，那么该文件就会作为项目的资源文件一同被添加，在 mytestcontrolplugin.cpp 中有一个 icon() 方法会设置自定义控件图标为你选择的这个图标。

        （🌐补：后续经过测试，这个 icon() 方法实际上是设置设计界面-对象窗口-自定义控件对象的图标，如下图所示：）

还是该页面，切换到“说明(D)”栏页面，设置“组(R)”名称。设置完成后，点击“下一步(N)”：

        “说明(D)”栏页面的 “组(R)” 、“工具提示(T)” 、“这是什么(H)” 内容都是可以后续在 mytestcontrolplugin.cpp 代码中更改的（分别对应代码中的 group() 方法、toolTip() 方法、whatsThis() 方法），所以不必急于在这里就决定它们的最终内容。不过需要注意的是，这三个栏都要求填入 ASCII 码字符，也就是不包含中文字符。

设置插件和资源文件名称，按默认即可，点击“下一步(N)”：

汇总页面，检查一下总共有哪些文件以及设置是否添加到版本控制系统(比如 SVN、Git 等)，这里我选择不添加到版本控制系统。点击“完成(F)”：

完成后可以看到项目管理窗口展示了本项目的目录结构：

        其中，mytestcontrol.pri 工程是我们编辑自定义控件的地方，而下面的 mytestcontrolplugin.h 与 mytestcontrolplugin.cpp 是用于把自定义控件编译为插件给 Qt Creator 使用的，在上面也提到了，我们可以在 mytestcontrolplugin.cpp 中设置自定义控件的一些属性。

        这里我们发现，自定义控件默认是没有 *.ui 文件的，如果我们需要ui文件来设计控件的话，此时有两个选择：

1. 单独添加一个 .ui 文件到 .pri 工程中；(比较麻烦，我选择偷懒)
2. 将 .pri 工程下的控件类整体替换为设计师界面类；(简单粗暴，我喜欢)

这里我采用了第二种方法，首先删除 .pri 工程下原有的 .h 和 .cpp 文件：

在弹出的对话框中勾选“永久删除文件”，点击“OK”：

紧接着又弹出对话框询问是否也删除 .pri 和 .cpp 文件，这里我们选择“No”(因为 .pri 文件还要留着有用)：

接着对 mytestcontrol.cpp 再做一遍同样的删除操作，这里就不演示了，.h 和 .cpp 文件删除完成后如下所示：

接下来往 .pri 工程中添加设计师界面类，右击 mytestcontrol ，选择“Add New...”：

找到 Qt 分类下的 Qt 设计师界面类 模板，点击“选择”：

选择“Widget”界面模板，其他保持默认，点击“下一步(N)”：

修改类名，这里类名建议与我们刚才删掉的控件类(C)名一致，否则还要去修改 .pri 文件的内容，点击“下一步(N)”：

汇总页面，这里特别注意“添加到项目(P)”下拉框选择 .pri 项目（默认是添加到 .pro 项目），点击“完成(F)”：

到这里，我们就成功将 .pri 工程下的控件类整体替换为设计师界面类了，替换完成后如下所示：

上述内容完成后，在 Qt Creator 左下角将构建模式更改为“Release”，点击“构建项目”按钮（或者按Ctrl +B）：

不出意外的话，应该会构建成功并给出如下两个warning：

根据给出的警告信息提示，我们来到 mytestcontrolplugin.h 的第 4 行，按下方代码修改引用头文件即可：

#include <QtUiPlugin/QDesignerCustomWidgetInterface>

为了方便演示，我们前往 mytestcontrolplugin.ui ，为我们自定义控件添加一个按钮：

最后，我们前往 mytestcontrol.h ，添加一个头文件引用，以及添加一个宏：

#include <QtUiPlugin/QDesignerExportWidget>

//宏（注意下图演示的添加位置）
QDESIGNER_WIDGET_EXPORT

        关于 QDESIGNER_WIDGET_EXPORT 宏的介绍与用处，可以参考 Qt 的官方文档。简单来说，我们可以在定义自定义微件(widgets)时使用此宏，以确保从插件中正确导出小部件以供Qt Designer使用。

完成后保存所有修改，随后在项目管理窗口右击项目名称，选择“重新构建”：

在 Qt Creator 的右下角有构建进度条，当进度条填满为绿色时，说明构建成功。可以看到，之前给出的两个warning也没了：

到这里，自定义控件就算大功告成啦！

---

        向Qt Creator添加插件：

构建完成后，我们打开自定义控件项目所在的文件夹，可以看到这里生成了一个名称结尾为“Release”的文件夹：

进入该文件夹，可以看到里面有一个 .so 文件( *.so 文件是Linux下的动态链接库文件，相当于Windows下的 *.dll 文件)，复制该文件：

随后分别把它拷贝到以下两个目录下（这里提供的目录仅作参考，请根据自身实际情况找到对应目录）：

/home/xjy/Qt5.14.2/5.14.2/gcc_64/plugins/designer

/home/xjy/Qt5.14.2/Tools/QtCreator/lib/Qt/plugins/designer

然后重启 Qt Creator，随便打开另外一个带设计界面的Qt项目，我们就能在设计界面的控件栏找到我们自定义的控件了：

这样我们就可以像拖动普通Qt控件一样拖动我们的自定义控件添加到界面了。是但可以看到，拖动到界面之后，自定义控件默认是以最小的尺寸展示的，这是因为我们没有设置自定义控件的baseSize：

手动拖拽控件大小后可以看到，这就是我们刚刚自定义的那个控件：

到这里，我们已经成功向Qt Creator添加了自定义控件插件了！

---

        在其他项目中引用自定义控件：

        值得一提的是，虽然我们已经可以在别的项目的设计界面内直接拖动添加我们的自定义控件了，但如果我们添加控件后直接运行的话还是会给出如下一系列错误：

        这是因为我们还未在目标项目中添加对自定义控件的源文件的引用。我们知道Qt项目中常用的构建系统(build system)有 qmake 和 Cmake ，接下来会有两小节篇幅分别介绍如何在使用 qmake 或 Cmake 的项目中引用自定义控件。

        在使用qmake的项目中引用自定义控件：

        方式一 —— 添加外部库（推荐）

首先笔者新建了一个基于 qmake 的Qt Widgets Application，这里就不演示新建过程了，完成后如下图所示：

右键项目名称，选择“添加库...”：

在打开的窗口中，选择“外部库”，点击“下一步(N)”：

接着设置库文件路径(即自定义控件构建后生成的那个 .so 文件的路径)，笔者使用的Ubuntu平台，故只用勾选Linux选项。设置完毕后点击“下一步(N)”：

最后是汇总页面，在这里可以看到 Qt Creator 会向 pro 文件添加哪些内容，点击“完成(F)”：

完成后，我们需要前往自定义控件项目所在文件夹，拷贝自定义控件的头文件：

mytestcontrol.h

随后将其粘贴到目标项目所在文件夹（与目标项目的 .pro 文件同目录）：

回到 Qt Creator，保存所有修改，重新构建 项目然后 运行 就可以啦！运行效果如下：

        方式二 —— pri 项目整体移植

首先笔者新建了一个基于 qmake 的Qt Widgets Application，这里就不演示新建过程了，完成后如下图所示：

随后我们去到自定义控件项目所在文件夹，复制该文件夹下的 .pri 文件以及 pri 项目下的 .h、.cpp、.ui文件：

mytestcontrol.pri
mytestcontrol.h
mytestcontrol.cpp
mytestcontrol.ui

随后又去到目标项目所在文件夹，粘贴这几个文件：

回到 Qt Creator，在目标项目的 .pro 文件内添加如下内容：

include(mytestcontrol.pri)

# 根据你的自定义控件pri项目名修改include括号内内容

然后保存所有修改，点击 构建 / 重新构建 或者直接 运行 就可以啦！运行效果如下：

---

        在使用Cmake的项目中引用自定义控件：

首先笔者新建了一个基于 Cmake 的Qt Widgets Application，这里就不演示新建过程了，完成后如下图所示：

        这里简单提一下，Cmake 是根据一个叫 CMakeLists.txt（组态档）的文件去生成 makefile 的。使用 Qt Creator 打开采用 Cmake 构建系统的项目时，选择 CMakeLists.txt 文件，点击“打开”即可顺利展开项目。

随后我们去到自定义控件项目所在文件夹，复制该文件夹 pri 项目下的 .h、.cpp、.ui文件：

mytestcontrol.h
mytestcontrol.cpp
mytestcontrol.ui

随后又去到目标项目所在文件夹，粘贴这几个文件：

回到 Qt Creator，在目标项目的 CMakeLists.txt 文件内添加如下内容：

set(CUSTOMCONTROL_SOURCES
        mytestcontrol.cpp
        mytestcontrol.h
        mytestcontrol.ui
)

# 添加内容插入位置推荐挨着set(PROJECT_SOURCES ...)语句，set语句在Cmake中用于设置变量
# 我这里设置的变量名是 “CUSTOMCONTROL_SOURCES”，小伙伴们可根据喜好自行修改其他名称

        这里提一下，uic、rcc、moc 都是 Qt 元对象系统的工具，如果你的使用 Cmake 的项目的 CMakeLists.txt 内没有如下几句代码：

set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)

        请将它们添加进去。

当然，set语句在Cmake中用于设置变量，仅仅设置了变量还没使用该变量所以自定义控件还没有真正被引入到目标项目中来。我们继续在 CMakeLists.txt 中添加如下内容：

${CUSTOMCONTROL_SOURCES}

#  ${VariableName} 语法用于访问名字为 VariableName 的变量的值（变量名区分大小写）

😃注：添加内容插入的位置请根据自身实际情况决定，这里仅做参考~

然后保存所有修改，点击 构建 / 重新构建 或者直接 运行 就可以啦！运行效果如下：