qt creator源码全方面分析(2-10-2)

Posted 2021-03-08 codeforfamily

目录

• Creating Your First Plugin
  • 创建一个插件项目
  • 构建并运行插件
  • 文件结构
  • qmake项目
  • 插件元数据模板
  • 插件类
    • 头文件
    • 源文件

Creating Your First Plugin

本节介绍，如何使用Qt Creator提供的插件模板，来创建Qt Creator插件，并获取对插件的组成和结构的第一印象。

创建一个插件项目

Qt Creator附带了一个创建Qt Creator插件的向导，该向导会为您创建一个可运行的最小插件。我们强烈建议您使用两个不同的Qt Creator实例来开发和测试您的插件。否则，您的插件也可以被加载到您的开发环境中，但如果你的插件不稳定，这会使开发环境也不稳定。 您可以仅仅创建Qt Creator的一个拷贝，使用一个进行实际开发，而使用另一个来测试插件。

您需要确保，你使用的用来创建插件的Qt Creator的版本要相同。 由于Qt Creator的二进制和源代码兼容性规则(https://www.cnblogs.com/codeForFamily/p/qt-creator-ide-source-learn-2-1-1.html)，Qt Creator插件向导创建了一个插件，该插件只能在创建时使用的Qt Creator版本中运行。

1. 选择文件>新建文件或项目>库>Qt Creator插件>选择

项目介绍和位置对话框被打开。

1. 为您的项目命名，并指定该项目的路径。 实际插件的名称可以与项目名称不同。 稍后您将在向导中选择该名称。 继续下一页。

   套件选择对话框被打开。

1. 选择用于构建和运行项目的套件。 对于Qt Creator插件，套件必须是桌面设备类型，而Qt版本必须是构建插件时所用的Qt Creator的Qt版本（最好是完全相同的）。 如果您使用不兼容的Qt版本来构建插件，则Qt Creator尝试加载插件时，会出现错误。 继续下一页。

   插件信息对话框被打开。

1. 在插件名称字段中，键入Example。插件的名称将作为标识符，并且也是代码中文件名和类的基础。

2. 以下字段的值是主要信息，并显示在Qt Creator的插件概述的详细视图中（帮助>关于插件，或者在Mac上为Qt Creator>关于插件）。

   • Vendor name是创建插件的公司或组织的简称。这也用于插件部署的路径名。

   • Copyright就一行，简短的版权字符串。

   • License是许可证文本。

   • Description是插件功能的简短描述。

   • URL是一个网站，用户可以在其中找到有关插件和/或提供插件的组织的更多信息。

3. 设置Qt Creator源文件和Qt Creator构建字段，分别输入您要用来测试插件的Qt Creator实例的源文件和构建目录。如果您未正确执行此操作，则将导致插件编译错误，并且您的插件可能根本不会出现在Qt Creator中。

4. 在部署到列表中，选择Qt Creator构建。这将.pro文件设置为，直接部署插件到Qt Creator构建目录的插件子目录中（要求具有写权限）。另一个选项，本地用户设置，将.pro文件设置为，部署插件到Qt Creator的用户插件路径中（例如Unix系统上的~/.config/QtProject/qtcreator/plugins）。我们选择Qt Creator构建，是因为我们使用自编译Qt Creator，并且希望插件仅被该Qt Creator实例加载。继续下一页。

   项目管理对话框被打开。

1. 查看将要创建的文件，选择Qt Creator项目使用的版本控制系统（这是一个好主意！），然后完成向导。

构建并运行插件

如果您在项目向导中传递了正确的Qt Creator源文件和构建路径，则在按下构建按钮时，您的插件应该可以很好地被构建。 当您尝试运行你的项目时，Qt Creator将询问您要运行的可执行文件，并显示以下对话框：

在构建中选择Qt Creator可执行文件的路径，路径在项目向导的Qt Creator build设置中指定，然后单击“确定”。 Qt Creator启动，您可以验证插件是否已成功加载：查找菜单项Tools > Example，然后在关于插件对话框中查找插件。

文件结构

插件向导会创建一组插件需要或应该具备的基础文件。 我们将在以下各节中详细介绍其中的一些内容，这是一个简短的概述：

文件	角色
Example.json.in	插件元数据模板。QMake根据此文件创建Example.json，该文件作为元数据编译到插件中。 Qt Creator读取元数据以了解有关插件的信息。
example.pro	项目文件，QMake使用该文件生成Makefile，然后用于插件构建。
example_global.h	包含宏定义，此插件将符号导出给其他插件时，非常有用。
exampleconstants.h	头文件，定义了插件代码使用的常量。
exampleplugin.h/.cpp	C++头文件和源文件，定义将由Qt Creator插件管理器实例化并运行的插件类。

qmake项目

qmake项目文件example.pro定义了如何编译插件。 除了告诉qmake需要编译哪些文件之外（或由moc或uic处理），Qt Creator插件还需要进行特定设置。 让我们详细了解一下项目向导为您生成的内容。

  DEFINES += EXAMPLE_LIBRARY

.pro文件的第一部分允许编译器传递Example_LIBRARY定义给已编译的代码，该定义已在example_global.h头文件中使用，但目前尚无真正意义。 您无需更改.pro文件的该部分。

  SOURCES += exampleplugin.cpp

  HEADERS += exampleplugin.h           example_global.h           exampleconstants.h

此部分告诉qmake需要进行编译或其他处理的项目文件。您可以使用你要添加到项目中的任何文件，来扩展该部分。

  ## set the QTC_SOURCE environment variable to override the setting here
  QTCREATOR_SOURCES = $$(QTC_SOURCE)
  isEmpty(QTCREATOR_SOURCES):QTCREATOR_SOURCES=/Users/example/qtcreator-src

  ## set the QTC_BUILD environment variable to override the setting here
  IDE_BUILD_TREE = $$(QTC_BUILD)
  isEmpty(IDE_BUILD_TREE):IDE_BUILD_TREE=/Users/example/qtcreator-build

要编译和部署您的插件，该项目需要访问Qt Creator源代码，然后进行构建。 此部分包含寻找有关源代码位置信息的逻辑，并在QTC_SOURCE和QTC_BUILD环境变量中进行构建。 如果它们未定义，它将使用您在项目向导中设置的默认值。

因此，如果其他人在他们的计算机上打开您的插件项目，他们不需要编辑.pro文件，而是应该为插件的构建环境设置正确的QTC_SOURCE和QTC_BUILD环境变量。

您可能不需要更改此部分，除非可以更改默认值

## uncomment to build plugin into user config directory
  ## <localappdata>/plugins/<ideversion>
  ##    where <localappdata> is e.g.
  ##    "%LOCALAPPDATA%QtProjectqtcreator" on Windows Vista and later
  ##    "$XDG_DATA_HOME/data/QtProject/qtcreator" or "~/.local/share/data/QtProject/qtcreator" on Linux
  ##    "~/Library/Application Support/QtProject/Qt Creator" on Mac
  # USE_USER_DESTDIR = yes

Qt Creator插件既可以安装到Qt Creator安装路径中的插件子目录（需要写访问权限），也可以安装到用户特定的插件目录。 .pro文件中的USE_USER_DESTDIR开关定义了用于构建插件的方法（该方法与后面用于将插件分发给其他用户的方法无关）。

  ###### If the plugin can be depended upon by other plugins, this code needs to be outsourced to
  ###### <dirname>_dependencies.pri, where <dirname> is the name of the directory containing the
  ###### plugin's sources.

  QTC_PLUGIN_NAME = Example
  QTC_LIB_DEPENDS +=       # nothing here at this time

  QTC_PLUGIN_DEPENDS +=       coreplugin

  QTC_PLUGIN_RECOMMENDS +=       # optional plugin dependencies. nothing here at this time

  ###### End _dependencies.pri contents ######

此部分定义插件的名称和依赖项。 QTC_PLUGIN_NAME变量定义了插件的名称，以及为其创建的动态库的名称。 QTC_LIB_DEPENDS变量是您的插件所依赖的Qt Creator实用工具库的列表。 典型的值是aggregation，extensionsystem和utils。 QTC_PLUGIN_DEPENDS变量定义您的插件所依赖的Qt Creator插件。 几乎所有Qt Creator插件都依赖coreplugin。QTC_PLUGIN_RECOMMENDS变量定义了您的插件可以选择性依赖的Qt Creator插件。 有关更多信息，请参见Optional Dependencies。

  include($$QTCREATOR_SOURCES/src/qtcreatorplugin.pri)

包含的qtcreatorplugin.pri文件，通过使用上面提供的信息，确保您构建适合在Qt Creator中使用的插件。

有关qmake和一般编写.pro文件的更多信息，请参见qmake手册。

插件元数据模板

.json文件是一个JSON文件，包含插件管理器查找您的插件的信息，以及在加载插件库文件之前解析依赖项所需的信息。 在这里，我们将仅作简短介绍。 有关更多信息，请参见Plugin Meta Data。

向导实际上并不直接创建.json文件，而是创建一个.json.in文件。 qmake使用它来生成实际的插件.json元数据文件，用其实际值替换QTCREATOR_VERSION之类的变量。 因此，您需要对.json.in文件中的所有反斜杠和引号进行转义（即，您需要写入和"，用来在生成的插件JSON元数据中得到反斜杠和引号）。

    "Name" : "Example",
    "Version" : "0.0.1",
    "CompatVersion" : "0.0.1",

元数据中的第一项由项目向导中定义的插件的名称生成，第二项是插件版本，第三项是当前版本能二进制兼容的此插件的版本。

    "Vendor" : "My Company",
    "Copyright" : "(C) My Company",
    "License" : "BSD",
    "Category" : "Examples",
    "Description" : "Minimal plugin example.",
    "Url" : "http://www.mycompany.com",

之后，您将找到在项目向导中提供的有关插件的信息。

    $$dependencyList

$$dependencyList变量会被插件.pro文件中的QTC_PLUGIN_DEPENDS和QTC_PLUGIN_RECOMMENDS中的依赖项信息自动替换。

插件类

文件exampleplugin.h和exampleplugin.cpp定义了您的小插件的实现。 我们将在这里介绍一些重点，并为各个部分提供更详细的信息的链接。

头文件

头文件exampleplugin.h定义了插件类的接口。

  namespace Example {
  namespace Internal {

该插件定义在Example::Internal名称空间，该名称空间符合Qt Creator源代码中 namespacing的编码规则。

  class ExamplePlugin : public ExtensionSystem::IPlugin
  {
      Q_OBJECT
      Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QtCreatorPlugin" FILE "Example.json")

所有Qt Creator插件都必须从ExtensionSystem::IPlugin派生，并且是QObjects派生类。 Q_PLUGIN_METADATA宏对于创建有效的Qt插件是必需的。 宏中给定的IID必须是org.qt-project.Qt.QtCreatorPlugin，用于标识插件为Qt Creator插件，并且FILE必须指向该插件的元数据文件，描述见Plugin Meta Data。

      bool initialize(const QStringList &arguments, QString *errorString);
      void extensionsInitialized();
      ShutdownFlag aboutToShutdown();

基类定义了在插件生命周期中调用的基本函数，在此处需要新插件实现。Plugin Life Cycle详细描述了这些函数及其作用。

  private:
      void triggerAction();

该插件有一个附加的自定义槽，用于弹出对话框，在用户选择该插件添加的菜单项时。

源文件

源文件包含插件的实际实现，注册了一个新菜单和子菜单项，并在触发子菜单项时，打开一个消息框。

来自插件代码本身，Core插件和Qt的所有必需的头文件都包含在文件的开头。 菜单和子菜单项在插件的initialize初始化函数中完成设置的，该函数在插件构造函数完成之后的最先被调用。在该函数中，插件可以确保其依赖的插件的基本设置已完成，例如，Core插件的ActionManager实例已被创建。

有关插件接口实现的更多信息，请参见ExtensionSystem::IPlugin API文档和Plugin Life Cycle。

      QAction *action = new QAction(tr("Example Action"), this);
      Core::Command *cmd = Core::ActionManager::registerAction(action, Constants::ACTION_ID,
                                              Core::Context(Core::Constants::C_GLOBAL));
      cmd->setDefaultKeySequence(QKeySequence(tr("Ctrl+Alt+Meta+A")));
      connect(action, &QAction::triggered, this, &ExamplePlugin::triggerAction);

这部分代码创建一个新的QAction，将其注册为动作管理器中的新Command，并将其连接到插件的槽。 动作管理器提供了一个中心位置，用户可以在该位置分配和更改键盘快捷键，并进行管理，例如菜单项应在不同情况下指向不同的插件，以及其他一些情况。

      Core::ActionContainer *menu = Core::ActionManager::createMenu(Constants::MENU_ID);
      menu->menu()->setTitle(tr("Example"));
      menu->addAction(cmd);
      Core::ActionManager::actionContainer(Core::Constants::M_TOOLS)->addMenu(menu);

在这里，将创建一个新菜单，并添加已创建的命令，然后将菜单添加到菜单栏中的工具菜单中。

  void ExamplePlugin::triggerAction()
  {
      QMessageBox::information(Core::ICore::mainWindow(),
                               tr("Action Triggered"),
                               tr("This is an action from Example."));
  }

这部分定义了触发子菜单项时调用的代码。它使用Qt API打开一个消息框，该消息框显示内容丰富的文本和确定按钮。