# 如何創建 EmEditor 外掛

---

在 EmEditor 中，您可以用巨集，外部工具以及程式碼片段自動化所有的操作。然而，一些使用者，特別是程式設計師，可能還是喜歡自己編寫外掛程式。自己編寫外掛程式的優點有：

- 您可以用 Win 32 API 編寫 C++ 。
- 您可以編寫 GUI (Graphic User Interface，圖形使用者介面) 元素，例如對話方塊。
- 您可以在 EmEditor 中使用自訂列和視窗，自訂工具列，還有輸出列。

另一方面，外掛的編寫需要使用到 **Microsoft Visual C++** ，是一個難度比較大的編程語言。但是，如果您已經習慣使用 C++ 或是 Win32 的話，編寫外掛程式對您來說應該是得心應手的一件事。

## Hello World 示例

如果您還沒有安裝Visual C++ 2012， 您可以在下面的鏈接中下載并安裝**Visual Studio Express 2012 for Windows Desktop**:

- [Visual Studio Express 2012 (Windows 桌面)](http://www.microsoft.com/visualstudio/eng/products/visual-studio-express-products)

您可以下載這個 <em>Hello World!!</em> 示例:

- [Hello World 外掛示例源代碼 (Version 11)](https://github.com/Emurasoft/HelloWorld)

在下載這個檔案之后，請把它提取到一個資料夾，然后用 Visual C++ 打開 Hello.sln 解決方案檔案，您將會在這個 *Hello* 項目中看到下面的一系列檔案。

|  File name  |                    用途                    | 需要編輯嗎？ |
|-------------|--------------------------------------------|--------------|
| etlframe.h  | ETL (EmEditor Template Library) 標頭檔     | 否           |
| hello.h     | Hello World 外掛實作檔                     | 是           |
| plugin.h    | EmEditor 外掛標頭檔                        | 否           |
| resource.h  | Hello World 外掛資源檔案                   | 是           |
| stdafx.h    | 先行編譯標頭檔                             | 也许         |
| bitmap1.bmp | 工具列按鈕點陣圖 (16 colors, 16×16 pixels) | 是           |
| hello.rc    | Hello World 外掛資源                       | 是           |
| hello.cpp   | Hello World 外掛實作檔                     | 也許         |
| hello.def   | 定義檔                                     | 否           |

在這些檔案中，需要編輯的檔案是 **hello.h**，**hello.rc**，**resource.h**，還有 **bitmap1.bmp**。如果您想要添加標頭檔的話，您也可以修改 **hello.cpp** 和 **stdafx.h**。其余的檔案中，**plugin.h** 和 **etlframe.h** 是由 Emurasoft 公司提供的標頭檔并不需要修改。 請到下面的鏈接中下載最新版本的標頭檔：

- [plugin.h](https://github.com/Emurasoft/HelloWorld/blob/master/plugin.h)
- [etlframe.h](https://github.com/Emurasoft/HelloWorld/blob/master/etlframe.h)

另外，**hello.def** 是定義 EmEditor 可導出功能的檔案，這個檔案也不需要修改。

首先，先不做任何更改，用 Visual C++ 打開這個項目并生成一個檔案。然后您將會看見出現了一個 **Hello.dll** 檔案。把這個檔案復制到 EmEditor 安裝目錄下的<strong>PlugIns (外掛)</strong>子資料夾中。通常，檔案的路徑是：*C:Program FilesEmEditorPlugIns*。接著，打開 EmEditor，您將會看到**外掛**工具列上出現一個黃色的圓圈按鈕。當您按下這個按鈕， EmEditor 編輯器中就會顯示 *Hello World!!* 的文字。

接下來，讓我們來更改這個示例，讓這個外掛能打開輸出列并在輸出列上顯示 *Hello World!!* 的文字。

## 最重要的函數：OnCommand

在 **hello.h** 檔案中最最重要的函數就是 **OnCommand**。當使用者從功能表上選擇這個外掛或點擊這個外掛按鈕時，就需要用到 OnCommand。通過更改這個函數內容，您可以改變這個外掛的行為。在這個例子中，請先刪除已存在的 **Editor_InsertW** 函數，然后添加下面的 **Editor_OutputString** 函數。

```cpp
// Editor_InsertW( hwndView, L"Hello World!!n", true );
Editor_OutputString( hwndView, L"Hello World!!n", FLAG_OPEN_OUTPUT );
```

上面所示以 **Editor_** 開頭的函數被定義在 **plug-in.h** 檔案中。當您用 EmEditor 打開 hello.h 后，請把游標移到以 **Editor_** 開頭的函數，然后按一下 **F1** 在說明中查看該函數的描述。

在 **hello.h** 檔案中，還有一個重要的函數，就是 **QueryStatus**。當 EmEditor 顯示一個菜單或者它需要進行更新來刷新工具欄按鈕時，就會使用到 **QueryStatus** 函數。當外掛被啟用時，這個函數會還原 TRUE 值。

```cpp
*pbChecked = TRUE
```

另外，這個函數還能檢查外掛功能表項目和工具列按鈕是否會在被點選的情況下出現。

**OnEvents** 函數會在一個檔案被打開，一個文檔被更新，或者其它各種事件發生時被使用。這一系列的事件的具體描述可以在 EmEditor 中的**說明** — **外掛參考** — **事件**中找到。在這些事件中，我們將改變 **EVENT_CHANGE** 事件使輸出列上能顯示 “*Text Changed!!*” 文本。要達到這個效果，我們首先要添加以下3行:

```cpp
if( nEvent & EVENT_CHANGE ){
    Editor_OutputString( hwndView, L"Text changed!!n", FLAG_OPEN_OUTPUT );
}
```

## 修改資源

接下來，我們要打開 **hello.rc** 檔案。這個檔案定義了各種字串，包括 **IDS_MENU_TEXT**，這個字串讓您能更改外掛的名稱。讓我們把外掛名字改為 “*Hello Test!*“。

```text
STRINGTABLE
BEGIN
    IDS_MENU_TEXT "Hello Test!"
    IDS_VERSION "1"
    IDS_SURE_TO_UNINSTALL "Are you sure you want to uninstall this Plug-in?"
END
```

另外，**bitmap1.bmp** 可以取代并保存您最喜歡的圖片。在這個例子中，我們會把它改成一個紅色的圓圈。

完成！您可以用Visual C++生成示例項目，您自訂的 **Hello.dll** 外掛就會被創建。您也可以把這個新的外掛復制到 *PlugIns* 子資料夾中，打開EmEditor，然后點擊外掛按鈕。”*Hello World!!*” 文字就會在輸出列中出現了。您也可以嘗試在文字編輯器中輸入新的文字，然后您就會在輸出列上看到您自己的定義的文字了。

## 自訂外掛備注

在上面的例子中，我們修改了 *Hello* 示例外掛。然而，當您想要創建一個新的外掛時，以下幾點您需要注意。首先要先準備一個定義檔案，像 **hello.def**，這個檔案定義了 DLL 檔案必須導出的函數。另外，**hello.def** 檔案一定要在 **Linker** – **Input** 中被標明是 **Module Definition File (模組定義檔)** 。而且，**__stdcall** 一定要在 **C/C++** – **Advanced** 中被標明是 **Calling Convention (呼叫慣例)**。在 **C/C++** – **Code Generation** 中，請選擇 **Multithread** <strong>(多執行緒)</strong> 而不是**Multithread DLL**。為使程式更**最佳化**，請選擇**支持小代碼**。這樣，外掛會程式會變小并減少對執行階段程式庫的依賴。

## 標準外掛原始程式碼

EmEditor中一些外掛的原始程式碼可以在下面的連結中下載:

- [Version 11 HTMLBar, OpenDocuments, Outline, Search, WordCount plug-in source code](http://www.emeditor.com/files/emeditor_plugins_src11-zip/)

您也可以參考下列的外掛原始程式碼:

- **HTMLBar** (HTML 工具列)
- **OpenDocuments** (打開的文檔)
- **OutlineText** (大綱)
- **Search** (搜尋)
- **WordCount** (計數)

在所有這些原始程式碼中，**HTMLBar** 是一個非常好的設置自訂工具列的參照。別的外掛也能夠幫助您創建自訂工具列。請參考這些原始程式碼來創建您自己的外掛。

我已經解釋了怎么創建 EmEditor 外掛。我們在這里所舉的例子只是一個非常簡單的例子。但是，您可以創建更加實用，有效，適合您自己的外掛！
