目錄

• 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，然後在關於外掛對話方塊中查詢外掛。

檔案結構

外掛嚮導會建立一組外掛需要或應該具備的基礎檔案。 我們將在以下各節中詳細介紹其中的一些內容，這是一個簡短的概述：

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%\QtProject\qtcreator" 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開啟一個訊息框，該訊息框顯示內容豐富的文字和確定按