Qt之自定义插件（for Qt Designer）

之前Blog里面有关于QWT的编译、配置、使用的文章，分别是在VS与Creator下进行的。

• QWT编译、配置、使用（VS2010 + Qt5.1.0）.
• QWT编译、配置、使用（Qt Creator）.

    里面介绍了如何将QWT集成到Designer中。如果认真研究过的话，那么对Designer中使用插件应该就不再陌生了。

    下面介绍下自己如何去实现一个插件并将其应用到Designer中。

    也可参考：Creating Custom Widgets for Qt Designer.

插件介绍：

    Qt Designer基于插件的架构允许用户自定义和第三方的自定义窗口部件进行编辑，就像用标准的Qt控件一样。所有的自定义部件功能提供给Qt Designer，包括部件属性，信号和槽。由于Qt Designer在设计过程中采用真实部件，所以预览的时候自定义部件会和设计阶段的一样。

    好的，那先上一个预览的效果吧！

    如图，Designer中包含了自定义插件（Clock、Qled）以及第三方插件（QWT），好的，先看看效果，后面会有具体讲解怎么实现的，慢慢来。。。

    要为Qt Designer集成自定义窗口部件，则需要一个合适的窗口部件和适当的.pro文件。

提供了一个接口描述

    为了通知Qt Designer想要提供窗口部件的类型，则需要创建一个QDesignerCustomWidgetInterface的子类，其中描述了部件暴露的各种属性，其大多数是由基类中的纯虚函数提供的，因为只有插件的作者可以提供这方面的信息。

编号	函数	返回值描述
1	name()	提供了插件的类名称
2	group()	该控件所属的组中的Qt Designer的小工具盒
3	toolTip()	一个简短的说明，以帮助用户识别Qt Designer中的部件
4	whatsThis()	为Qt Designer用户设计的部件一个较长的描述
5	includeFile()	头文件必须包含在使用该插件的应用程序的。此信息存储在UI文件中，并将由UIC创建用于包含自定义插件形式的代码合适的#includes语句。
6	icon()	Qt Designer的插件箱中小窗口的图标
7	isContainer()	true表示部件将用来保存子部件，否则为false
8 9 10	createWidget() domXml() codeTemplate()	一个指向自定义窗口小部件的QWidget指针实例，构建了所提供的父母。 注：createWidget()是一个工厂方法，只负责创建小部件的功能。自定义窗口小部件的属性将不可用，直到load()返回。 描述了部件的属性，例如：对象名称、大小提示，以及其它标准的QWidget属性的描述。 这个函数是预留给Qt Designer将来使用的

    其它两个虚函数也可以重新实现

编号	函数	返回值描述
11	initialize()	设置了自定义窗口部件扩展等功能。自定义容器扩展（见QDesignerContainerExtension）和任务菜单扩展（见QDesignerTaskMenuExtension）应在此函数中设置。
12	isInitialized()	如果该部件已被初始化，则返回true；否则返回false。重新实现通常检查initialize()函数是否已被调用，并返回本次测试的结果。

domXml() 函数的注意事项：

    domXml()函数返回一个UI文件代码段，使用Qt Designer窗口工厂创建一个自定义窗口部件和使用特性。

    从Qt4.4开始，Qt Designer的窗口部件中允许一个完整的UI文件来描述一个自定义窗口部件。UI文件可以使用标签加载。指定标签允许添加元素，其中包含自定义窗口部件的其它信息。如果不需要更多的信息，那么标签已经足够了。

    如果自定义窗口部件不提供合理的尺寸，有必要通过在子类的domXml()函数返回的字符串中指定默认的位置大小（geometry）。例如，由自定义的Widget插件示例提供的AnalogClockPlugin，通过下面的方式来指定默认的部件位置大小：

    ...
           "  \n"
           "   \n"
           "    0\n"
           "    0\n"
           "    100\n"
           "    100\n"
           "   \n"
           "  \n"
    ...

    domXml()函数的另一个特点是，如果它返回一个空字符串，部件不会安装在Qt Designer的窗口部件盒中。然而，它仍然可以被其它形式的部件所使用。这个特性用来隐藏部件，不应由用户显式地创建，但需要其它部件创建。

     一个完整的自定义部件格式是这样的：

 displayname="MyWidget">

            widgets::MyWidget
            addPage

标签的属性：

属性	呈现形式	值	内容
language	可选项	"c++", "jambi"	这个属性指定了自定义窗口部件提供的语言。 主要有防止C++插件出现在Qt Jambi中。
displayname	可选项	类名	属性的值将出现在小工具框，可以用来剥去命名空间。

    标签告诉Qt Designer和UIC应采用哪种方法将页面添加到一个容器组件中。这适用于容器构件需要调用特定的方法来添加一个孩子，而不是通过父亲来添加孩子。特别是，这是相关的容器，不是一个Qt Designer提供的子类容器，但是基于当前页面的概念。此外，您需要提供一个容器扩展他们。

    元素可以包含属性的元信息的列表。目前，支持字符串类型的属性。对于这些属性，所述标记都可以使用。该标签具有以下属性：

属性	呈现形式	值	内容
name	必须的	该属性的名称
type	必须	见下表	该属性的值决定了属性编辑器将如何处理它们。
notr	可选项	"true", "false"	如果属性是“true”，则该值意味着不再被翻译。

字符串属性的类型属性的值：

值	类型
"richtext"	富文本
"multiline"	多行纯文本
"singleline"	单行纯文本
"stylesheet"	一个CSS样式表
"objectname"	对象名称（受限制的一组有效字符）
"url"	URL、文件名.

插件要求

    为了让插件在所有平台上正常工作，你需要确保他们导出了Qt Designer所需要的符号。

    首先，插件类必须被Qt Designer加载的插件按顺序导出。使用Q_PLUGIN_METADATA()宏来做到这一点。此外，QDESIGNER_WIDGET_EXPORT宏必须被使用，来定义Qt Designer将实例化的插件中每一个自定义窗口部件类。

创建一个良好的插件：

    一些自定义窗口部件有专门的用户界面功能，可以使他们的行为不同于Qt Designer中的其它标准窗口部件。特别是，如果一个自定义小部件由于调用QWidget::grabKeyboard()来捕获键盘，Qt Designer的操作将受到影响。

    为了让自定义部件在Qt Designer有特殊行为，提供 initialize()函数来配置窗口部件运行过程中的特定行为。该函数在被第一次调用之前先调用createWidget()，可以设定一个内部标志来测试什么时候调用createWidget()函数。

1.构建插件

    为了简单期间，这里只提供QLed的源码，customwidgetplugin的源码可在安装目录中的Demo里面查找（例：D:\Qt\Qt5.1.1\5.1.1\msvc2010\examples\designer\customwidgetplugin）。

qledplugin.pro

#CONFIG      += designer plugin debug_and_release
#TARGET      = $$qtLibraryTarget($$TARGET)
#TEMPLATE    = lib
#QT += svg

#QTDIR_build:DESTDIR     = $$QT_BUILD_TREE/plugins/designer

CONFIG      += plugin
CONFIG      += designer
CONFIG      += debug_and_release
TEMPLATE    = lib
QT          += svg widgets designer

HEADERS     = qled.h \
              qledplugin.h
SOURCES     = qled.cpp \
              qledplugin.cpp

RESOURCES = qled.qrc

target.path = $$[QT_INSTALL_PLUGINS]/designer
INSTALLS += target sources

# install
#target.path = $$[QT_INSTALL_PLUGINS]/designer
#sources.files = $$SOURCES $$HEADERS *.pro
#sources.path = $$[QT_INSTALL_EXAMPLES]/designer/qledplugin
#INSTALLS += target sources

qled.h

#ifndef QLED_H
#define QLED_H

#include <</span>Qt>
#include <</span>QWidget>
#include <</span>QtDesigner/QDesignerExportWidget>

class QColor;
class QSvgRenderer;

class QDESIGNER_WIDGET_EXPORT QLed : public QWidget
{
    Q_OBJECT
    Q_ENUMS (ledColor)
    Q_ENUMS (ledShape)
    Q_PROPERTY(bool value READ value WRITE setValue);
    Q_PROPERTY(ledColor onColor READ onColor WRITE setOnColor);
    Q_PROPERTY(ledColor offColor READ offColor WRITE setOffColor);
    Q_PROPERTY(ledShape shape READ shape WRITE setShape)     

public:
    QLed(QWidget *parent = 0);
    virtual ~QLed();
    bool value() const { return m_value; }
    enum ledColor { Red=0,Green,Yellow,Grey,Orange,Purple,Blue };
    enum ledShape { Circle=0,Square,Triangle,Rounded};
    ledColor onColor() const { return m_onColor; }
    ledColor offColor() const { return m_offColor; }
    ledShape shape() const { return m_shape; }

public slots:
    void setValue(bool);
    void setOnColor(ledColor);
    void setOffColor(ledColor);
    void setShape(ledShape);
    void toggleValue();

protected:
    bool m_value;
    ledColor m_onColor, m_offColor;
    int id_Timer;
    ledShape m_shape;
    QStringList shapes;
    QStringList colors;
    void paintEvent(QPaintEvent *event);
private:
    QSvgRenderer *renderer ;
};

#endif

qled.cpp

#include
#include
#include
#include
#include
#include 

#include "qled.h"

QLed::QLed(QWidget *parent)
    : QWidget(parent)
{
    m_value=false;
    m_onColor=Red;
    m_offColor=Grey;
    m_shape=Circle;
    shapes << ":/resources/circle_" << ":/resources/square_" << ":/resources/triang_" << ":/resources/round_";
    colors << "red.svg" << "green.svg" << "yellow.svg" << "grey.svg" << "orange.svg" << "purple.svg" << "blue.svg";

    renderer = new QSvgRenderer();
}
QLed::~QLed() {
    delete renderer;
}

void QLed::paintEvent(QPaintEvent *)
{

    QString ledShapeAndColor;
    QPainter painter(this);
    painter.setRenderHint(QPainter::Antialiasing, true);

    ledShapeAndColor=shapes[m_shape];

    if(m_value)
        ledShapeAndColor.append(colors[m_onColor]);
    else
        ledShapeAndColor.append(colors[m_offColor]);

    renderer->load(ledShapeAndColor);
    renderer->render(&painter);

}

void QLed::setOnColor(ledColor newColor)
{
    m_onColor=newColor;
    update();
}

void QLed::setOffColor(ledColor newColor)
{
    m_offColor=newColor;
    update();
}

void QLed::setShape(ledShape newShape)
{
    m_shape=newShape;
    update();
}

void QLed::setValue(bool value)
{
    m_value=value;
    update();
}

void QLed::toggleValue()
{
    m_value=!m_value;
    update();
}

qledplugin.h

#ifndef CUSTOMWIDGETPLUGIN_H
#define CUSTOMWIDGETPLUGIN_H

#include <</span>QDesignerCustomWidgetInterface>
class QLedPlugin : public QObject, public QDesignerCustomWidgetInterface
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface" FILE "QLedPlugin.json")
    Q_INTERFACES(QDesignerCustomWidgetInterface)

public:
    QLedPlugin(QObject *parent = 0);

    bool isContainer() const;
    bool isInitialized() const;
    QIcon icon() const;
    QString domXml() const;
    QString group() const;
    QString includeFile() const;
    QString name() const;
    QString toolTip() const;
    QString whatsThis() const;
    QWidget *createWidget(QWidget *parent);
    void initialize(QDesignerFormEditorInterface *core);

private:
    bool initialized;
};

#endif

qledplugin.cpp

#include "qled.h"
#include "qledplugin.h"
#include <</span>QtPlugin>

QLedPlugin::QLedPlugin(QObject *parent)
    : QObject(parent)
{
    initialized = false;
}

void QLedPlugin::initialize(QDesignerFormEditorInterface * )
{
    if (initialized)
        return;

    initialized = true;
}

bool QLedPlugin::isInitialized() const
{
    return initialized;
}

QWidget *QLedPlugin::createWidget(QWidget *parent)
{
    return new QLed(parent);
}

QString QLedPlugin::name() const
{
    return "QLed";
}

QString QLedPlugin::group() const
{
    return "Led Widgets";
}

QIcon QLedPlugin::icon() const
{
    return QIcon(":resources/qled.png");
}

QString QLedPlugin::toolTip() const
{
    return tr("Led Custom widget Plugin fot Qt Designer");
}

QString QLedPlugin::whatsThis() const
{
    return tr("Led Custom widget Plugin fot Qt Designer");
}

bool QLedPlugin::isContainer() const
{
    return false;
}

QString QLedPlugin::domXml() const
{
    return "\n"
           " \n"
           "  \n"
           "   0\n"
           "   0\n"
           "   50\n"
           "   50\n"
           "  \n"
           " \n"
           " \n"
           "  Binary Led\n"
           " \n"
           " \n"
           " false\n"
           " \n"
           " \n"
           "  Led widget\n"
           " \n"
           " \n"
           " QLed::Red\n"
           " \n"
           " \n"
           " QLed::Grey\n"
           " \n"
           " \n"
           " QLed::Circle\n"
           " \n"
           "\n";
}

QString QLedPlugin::includeFile() const
{
    return "qled.h";
}

    我相信到这里所有的东西都已经很清楚了，记得不要忘记QLedPlugin.json文件喔，当然最后也不能少资源文件：

    经过编译，后会生成一个qledplugin.lib与qledplugin.dll，

2.配置插件

    qt安装目录以D:\Qt\Qt5.1.1\5.1.1\msvc2010为例：

（1）将编译好的qledplugin.dll拷贝到D:\Qt\Qt5.1.1\5.1.1\msvc2010\bin目录下，

   将qledplugin.lib拷贝到D:\Qt\Qt5.1.1\5.1.1\msvc2010\lib下

（2）将qledplugin.dll拷贝到D:\Qt\Qt5.1.1\5.1.1\msvc2010\plugins\designer目录下。

（3）将qled.h和qled.cpp放入一个空文件夹QLed中，再将该文件夹拷贝到D:\Qt\Qt5.1.1\5.1.1\msvc2010\include目录下。

3.使用插件

 新建项目，然后进行配置，主要看下.pro的写法，如下：  

QT       += core gui svg

greaterThan(QT_MAJOR_VERSION, 4): QT += widgets

TARGET = TestCustomWidgetPlugin
TEMPLATE = app

INCLUDEPATH += $$(QTDIR)/include/QCustomWidgetPlugin
INCLUDEPATH += $$(QTDIR)/include/QLed

LIBS += $$(QTDIR)/lib/customwidgetplugin.lib \
        $$(QTDIR)/lib/qledplugin.lib

SOURCES += main.cpp\
        widget.cpp

HEADERS  += widget.h

FORMS    += widget.ui

这样所有的任务都完成了，很轻松的就可以在designer里面设计并预览了。

效果如下：

注：

    技术在于交流、沟通，转载请注明出处并保持作品的完整性。

    作者：一去丶二三里  原文：http://blog.sina.com.cn/s/blog_a6fb6cc90102vsj1.html。