Qt系列——Qt5自定义控件（插件）封装SDK集成到QtDesigner和QtCreaterFramework中

Posted 2022-12-01 何以问天涯

在使用Qt Designer设计窗体界面时，我们可以使用Widget Box里的窗体控件非常方便的绘制界面，比如拖进去一个按钮，一个文本编辑器等。虽然Qt Designer里的控件可以满足我们大部分的需求，但是有时候，也会产生一些特殊的需要，比如一个仪表盘，我们要输入的是最大最小刻度值，仪表盘的量程、更新周期等。如果我们的多个窗体上都需要使用这个仪表盘，那么构造这样一个控件，将会非常方便，不需要手动修改颜色等参数属性。下面就以此为例，讲解一下如何创建自定义的窗体控件。

一、效果展示

为了直观显示本文章的意图，我们将制作后的自定义插件直观显示

下面讲解对应的自定义控件集成过程。

二、创建Qt 设计师自定义控件

打开Qt Creator,创建一个Qt 设计师自定义控件，如下图所示

这里我们选择MinGW 32bit编译器，mingw编译器生成为.a文件，如果是MSVC生成的是dll文件、lib，代码判断MSVC编译器版本，if (_MSC_VER == 1800)，对应关系2013=1800 2012=1700 2010=1600 2008=1500 2005=1400，Linux生成的是.so文件

根据向导提示，创建好工程，这里取名为GaugeSpeed，工程目录如下图所示，是个典型的错误，因为都是小写的：

自定义控件的名称不能小写，否则拖过去的控件自动生成的默认名称和类名一样，会编译通不过。这个问题坑很多，造成自动生成的UI代码保存，冲突导致的
正确的命名方式如下所示：

三、编译控件工程

每个Qt库bin目录的designer可执行文件都是和该库同一个编译器编译的，可用，如果想要集成到Qt Creator中，则需要注意版本，一般在windows上的Qt Creator版本是MSVC的，则需要对应的Qt库也是MSVC编译的，库版本和编译器版本必须保持一致才能是顺利集成到Qt Creator的重要前提。

编译完成后，在输出目录下，将生成的.dll文件和.a文件一起拷贝到Qt的插件目录下，以我使用的Qt 5.11.0为例，在Qt 5.11.0的安装目录F:\\Qt\\Qt5.11.0\\5.11.0\\mingw53_32下，找到plugins目录，在其中找到designer目录，然后把dlla放进去，完整路径为：F:\\Qt\\Qt5.11.0\\5.11.0\\mingw53_32\\plugins。

之后，启动F:\\Qt\\Qt5.11.0\\5.11.0\\mingw53_32\\bin下的designer.exe，创建一个窗体，此时就会发现在左侧的Widget Box里出现了我们自己的GaugeSpeed控件，我们可以像使用其它控件一样，把我们自己的控件拖绘到窗体上，如下图所示：

自定义控件类头文件引入，Qt5.7以下版本为#include <QtDesigner/QDesignerExportWidget> 以上版本为#include <QtUiPlugin/QDesignerExportWidget>
添加宏定义为

四、给自定义控件添加属性

窗体控件都有属性，比如QLineEdit就有text属性，另外还有设置属性，比如QLineEdit的readOnly属性。下面就讲解一下如何给自己的控件添加属性的问题。对于我们的仪表盘输入控件，它应该具有一个设置属性和一个值属性，我们把设置属性命名为getMinValue，把值属性命名为m_dMinValue，先来讲解设置属性getMinValue。
这里注意一下使用Q_PROPERTY宏声明属性的方法，它可以设置仪表盘的最小开始显示值，浮点输入模式，我们可以仿照其做法，实现输入模式属性，这里不多做解释，实现的其他属性为：

五、Qt Creator 使用自定义控件

控件编写完毕以后，把生成的dll和a文件一起拷贝到Qt安装目录下的插件目录里，比如我安装在F盘里的Qt 5.11.0，路径为：F:\\Qt\\Qt5.11.0\\5.11.0\\mingw53_32\\plugins\\designer，拷贝进去以后，这个插件就可以被Qt Designer加载了，此时这个自定义控件就可以像普通的控件一样使用了。当然如有必要，还可以给这个控件添加一些信号和槽，本例中不需要这么复杂，就不再深入探索了，下面是修改自定义的范围控件的效果：

到目前为止，我们已经可以在Qt Designer中使用自定义的控件绘制界面了，但是这个时候，事情还没有完，因为使用QtCreator时，会发现其界面设计器中并没有我们的自定义控件。另外当我们用Qt Designer绘制完控件后，编译时会发生找不到“GaugeSpeed.h”头文件的编译错误。这个问题很容易理解，首先我们可以想到的是Qt Creator和Qt Designer的自定义控件目录是不同的，我自己的机器里，Qt和Qt Creator的安装目录如下：
F:\\Qt\\Qt5.11.0\\5.11.0\\mingw53_32
F:\\Qt\\Qt5.11.0\\Tools\\QtCreator
因此，对于Qt Creator，我们也需要执行以下控件的安装，那么具体要安装到哪里去呢？经过在Qt Creator安装目录下一番查找，发现F:\\Qt\\Qt5.11.0\\Tools\\QtCreator\\bin\\plugins\\designer这个目录下存在和F:\\Qt\\Qt5.11.0\\5.11.0\\mingw53_32\\plugins\\designer目录下同名的dll文件，于是我们猜测这个目录就是Qt Creator的控件安装目录，接下来拷贝a和dll到这个目录下，之后重新打开Qt Creator，发现自定义控件加载成功了，于是第一个问题解决了。
还有注意：类名前必须加入 QDESIGNER_WIDGET_EXPORT 宏。否则集成到Qt Creator 中编译会报错。不加的话可以在设计器中加载，但是编译会报错。

如果将生成好的dll文件放到Qt库目录下的 plugins\\designer 下，可以在 designer 中看到。放到Qt Creator下的 bin\\plugins\\designer 则可以集成到Qt Creator中。

我们很容易想到使用一个动态库时，除了要有dll和lib文件外，还需要头文件，而对于某一版本的Qt SDK，发现编译可以通过，但是连接失败，尝试将相应的lib文件放到lib目录下并且把该lib库添加为工程的依赖库，依然连接失败。这表明Qt的自定义控件工程并没有导出我们的自定义控件，因此其生成的库文件gaugespeed.lib里并没有自定义控件的信息。因此要使用自定义控件，只能引入源码。

将自定义控件的头文件、dll文件、lib（mingw编译器为.a）文件复制出来，放到include（可自己随便命名，我这里习惯用include）目录，将include目录放到项目的源码文件下，在使用了自定义控件的项目的pro文件中，增加两行 INCLUDEPATH += $$PWD/include LIBS += $$PWD/include/***.lib(mingw编译器为.a)，这样可以正常编译，但是编译完成后不能运行，还需要将 对应自定义控件的dll文件复制到可执行文件同一目录即可，注意官网提供的Qt Creator版本基本上是MSVC版本，如果需要在mingw的Qt库对应的Qt Creator中集成自定义控件，需要自己用对应的Qt库编译Qt Creator源码。

参考文献

【1】Qt编写自定义控件插件路过的坑及注意事项 - 飞扬青云 - 博客园
https://www.cnblogs.com/feiyangqingyun/p/6182320.html#!comments
【2】Qt之自定义插件（for Qt Designer）_一去二三里_新浪博客
http://blog.sina.com.cn/s/blog_a6fb6cc90102vsj1.html
【3】(80条消息) Qt自定义控件的创建与初步使用（一）之自定义控件的创建步骤_panshun888的博客-CSDN博客_qt自定义控件
https://blog.csdn.net/panshun888/article/details/51923927