開發 Eclipse 外掛程式的最佳實務

第 1 部分：建立您自己的標記

標記是什嗎？

標記用於在不更改資源的情況下將資訊連結到資源上。被標記資訊的常見樣本有斷點、書籤和編譯錯誤。以編譯錯誤為例，每一次執行編譯作業，作業會通過建立一個新的標記來瀏覽源並突出錯誤。

 

回頁首

擴充標記

在本教程的第一部分，我們將建立我們自己的標記。只要通過標記延伸點，並且只要編寫一行代碼即可完成此項工作。

您可以通過擴充 IMarker 擴充點 org.eclipse.core.resources.markers 來建立您自己的標記。首先，在 plugin.xml 檔案中添加 清單 1 中的代碼。也就是說，您將以 id 為 com.ibm.mymarkers.mymarker 建立一個名為 My Marker 的標記。它的超類型為 org.eclipse.core.resources.marker。這是最基本的標記類型。您可以擴充其他提供稍微更具體的功能的超類型。其他的超類型有：

• org.eclipse.core.resources.problemmarker
• org.eclipse.core.resources.textmarker

注意：您可以隨需使用任意多的這些超類型。

清單 1. 清單 1 來自 plugin.xml 的標記延伸定義

<extension point="org.eclipse.core.resources.markers" id="com.ibm.mymarkers.mymarker" name="My Marker"><super type="org.eclipse.core.resources.marker"/><persistent value="false"/><attribute name="description"/></extension>

 

注意清單 1 中的兩個要素 persistent 和 attribute。這些都是分配給 mymarker 標記的屬性。 Persistent 指明標記是否應該儲存在工作區中。還有另外一個分配給 mymarker 的新屬性 description。

 

回頁首

使用新標記

您可以通過調用所需資源上的 createMarker 方法來建立一個標記。同時，您也可以為其設定屬性。

清單 2 中所示的方法也可以用來建立標記。只需輸入 IResource，將其連結到標記。建立後，您就可以設定其屬性。

清單 2. 清單 2 建立新標記類型的 Java 代碼

public static IMarker createMarker(IResource res)throws CoreException { IMarker marker = null; //note: you use the id that is defined in your plugin.xml marker = res.createMarker("com.ibm.mymarkers.mymarker"); marker.setAttribute("description," "this is one of my markers"); //note: you can also use attributes from your supertype marker.setAttribute(IMarker.MESSAGE, "My Marker"); return marker;}

 

 

回頁首

尋找您的標記

要尋找與 IResource 相關的標記，您可以查詢資源來擷取所有具有指定 id 的標記，並指定是否搜尋相關資源。要搜尋標記，調用資源上的 findMarkers 方法。指定諸如標記類型和搜尋深度的參數。

清單 3 中的代碼使用 IResource.DEPTH_ZERO 參數尋找直接與該資源連結的標記。

清單 3. 尋找新標記類型的 Java 代碼

public static final String MARKER = "com.ibm.mymarkers.mymarker";public static List<IMarker> findMarkers(IResource resource) { try { return Arrays.asList(resource.findMarkers(MARKER, true, IResource.DEPTH_ZERO)); } catch (CoreException e) { return new ArrayList<IMarker>(); } }

 

將資源深度更改為 IResource.DEPTH_INFINITE 會返回與其相關的標記或任何子資源。例如，您可以傳入包，並擷取與包中資源相連結的所有標記。

第 2 部分：使用注釋來顯示和更新標記

注釋是什嗎？

注釋用於標記編輯器內的一個文本地區。它們廣泛用於在 Eclipse 中顯示資訊，比如錯誤、警告、構建問題、任務或斷點。注釋在編輯器尺規上和文本上都可看到。圖 1 列出顯示語法錯誤的注釋。

圖 1. 圖 1 注釋的樣本

常見的注釋實現是，在解析檔案並且挑選出諸如錯誤和 “todo” 標籤時產生標記。這通常在構建時完成。將其他的連結到持久標記，如斷點。該樣本所使用的是持久標記。

使用者查看注釋的方法可以使用菜單 General > Editors > Text Editors > Annotations 下的喜好設定面板進行定製。也就是說使用者自訂注釋不需要執行額外的工作。

圖 2. 圖 2 注釋喜好設定面板的螢幕

查看 大圖。

 

回頁首

標記延伸點的屬性

在本教程的第 1 部分中，標記只擴充了預設的標記類型。在第 2 部分，我們將擴充文本標記類型，以標記文本位置。此類型定義了兩個關鍵屬性： charStart 和 charEnd。我們也希望標記在會話間能持久，所以我們將 persistent 值改為 true。為此，我們需要更新 清單 4 中所定義的標記。

清單 4. 清單 4 來自 plugin.xml 的標記延伸定義

<extension point="org.eclipse.core.resources.markers" id="com.ibm.mymarkers.mymarker" name="My Marker"><super type="org.eclipse.core.resources.textmarker"/><super type="org.eclipse.core.resources.marker"/><persistent value="true"/></extension>

 

回頁首

定義您的注釋規範擴充

要建立您自己的注釋，使用擴充點 org.eclipse.ui.editors.markerAnnotationSpecification（參見 清單 5）。它定義了注釋的屬性以及其預設顯示選項。

清單 5. 清單 5 來自 plugin.xml 的注釋擴充定義

<extension point="org.eclipse.ui.editors.markerAnnotationSpecification"id="myannotationspecification" name="MyAnnotation"><specification annotationType="com.ibm.example.myannotation"label="MyAnnotation"icon="icons/sample.gif"overviewRulerPreferenceKey="clruler"overviewRulerPreferenceValue="true"colorPreferenceKey="clcolor"colorPreferenceValue="255,255,0"textPreferenceKey="cltext"textPreferenceValue="true"verticalRulerPreferenceKey="clvertical"verticalRulerPreferenceValue="true"textStylePreferenceKey="clstyle"textStylePreferenceValue="BOX"></specification></extension>

XML 中我們將用來連結到規範的部分是 id 和 annotationType 屬性。Eclipse.org 記錄了用於自訂的其他屬性（參見 參考資料)。

下一步是使用擴充點 org.eclipse.ui.editors.annotationTypes 把現有的標記連結到新的注釋規範中。我們使用來自規範的注釋類型和來自標記定義的 id 來連結規範。

清單 6. 清單 6 來自 plugin.xml 的注釋類型定義

<extension point="org.eclipse.ui.editors.annotationTypes"> <type markerSeverity="0" super="org.eclipse.ui.workbench.texteditor.info" name="com.ibm.example.myannotation"markerType="com.ibm.mymarkers.mymarker"/></extension>

請參閱 參考資料，在 Eclipse.org 上尋找更多關於此擴充點的資訊。

 

回頁首

建立並添加一個注釋到編輯器

清單 7 中的代碼用於建立並添加註釋到編輯器。

清單 7. 清單 7 向編輯器添加一個新的注釋

public static void addAnnotation(IMarker marker, ITextSelection selection, ITextEditor editor) { //The DocumentProvider enables to get the document currently loaded in the editor IDocumentProvider idp = editor.getDocumentProvider(); //This is the document we want to connect to. This is taken from //the current editor input. IDocument document = idp.getDocument(editor.getEditorInput()); //The IannotationModel enables to add/remove/change annotation to a Document //loaded in an Editor IAnnotationModel iamf = idp.getAnnotationModel(editor.getEditorInput()); //Note: The annotation type id specify that you want to create one of your //annotations SimpleMarkerAnnotation ma = new SimpleMarkerAnnotation(“com.ibm.example.myannotation”,marker); //Finally add the new annotation to the model iamf.connect(document); iamf.addAnnotation(ma,newPosition(selection.getOffset(),selection.getLength())); iamf.disconnect(document);}

 

回頁首

保持標記和注釋同步

注釋模式負責在文檔被編輯時移動注釋。然而，在注釋移動時，它並不更新標記的屬性。在這種情況下，我們要更新標記的 charStart 和 charEnd 屬性。最後的擴充點為標記更新器（updater）。它定義了一個類，用於在移動注釋時更新標記。

清單 8. 清單 8 來自 plugin.xml 的標記更新器定義

<extension point="org.eclipse.ui.editors.markerUpdaters"> <updater id="com.ibm.example.MarkerUpdater" class="com.ibm.example.mymarker.MarkerUpdater" markerType="com.ibm.mymarkers.mymarker"> </updater></extension>:

我們使用 IMarkerUpdater 介面來提供我們在移動注釋時想要執行的代碼。清單 9 中顯示的類是我們的標記更新器。我們感興趣的代碼在 updateMarker 方法中。 此處，我們用它來更新標記的 charStart 和 charEnd 屬性。

清單 9. 清單 9 標記更新器代碼

public class MarkerUpdater implements IMarkerUpdater { /* *Returns the attributes for which this updater is responsible. *If the result is null, the updater assumes responsibility for any attributes. */ @Override public String[] getAttribute() { return null; } @Override public String getMarkerType() { //returns the marker type that we are interested in updating return "com.ibm.mymarkers.mymarker"; } @Override public boolean updateMarker(IMarker marker, IDocument doc, Position position) { try { int start = position.getOffset(); int end = position.getOffset() + position.getLength(); marker.setAttribute(IMarker.CHAR_START, start); marker.setAttribute(IMarker.CHAR_END, end); return true; } catch (CoreException e) { return false; } }}

第 3 部分：使用修飾符來識別已標記的 IResources

修飾符是什嗎？

在 Eclipse 中，修飾符用於為工作區中的對象添加視覺資訊。他們通常顯示物件類型以及目前與該對象相關的任何重要屬性。圖 3 顯示了如何在包資源管理員中將修飾符顯示給使用者。該修飾符顯示了哪些項為 Java 源檔案，或哪些項為包，並且顯示了包含警告或錯誤的源和包的標記表徵圖。這裡，修飾符也用來添加細節，比如檔案是否與存放庫同步。

圖 3. 圖 3 用符號地圖標修飾的包和源

 

回頁首

定義您自己的修飾符

添加我們的修飾符的第一步是擴充 org.eclipse.ui.decorators 擴充點。它啟用新修飾符的定義，並且選擇它將要修飾哪種對象。

此處重要的欄位是：

• class，它必須是實現 ILightweightLabelDecorator 的類的完全限定名（將 lightweight 設定為 true）。
• enablement，它包含修飾符所應用的 Eclipse 對象列表。

清單 10. 清單 10 來自 plugin.xml 的修飾符定義

<extension point="org.eclipse.ui.decorators"> <decorator id="com.ibm.example.filedecorator" label="MyMarker Decorator" state="true" class= "com.ibm.example.mymarker.FileDecorator" adaptable="true" lightweight="true"> <enablement><objectClass name="org.eclipse.core.resources.IResource"/> </enablement> </decorator></extension>

請參閱 參考資料，在 Eclipse.org 上尋找更多關於擴充點的檔案。

注意：輕量級與非輕量級：根據 API， 非輕量級修飾符可能會在新版本的 Eclipe 中被棄用。

 

回頁首

我們的檔案修飾符類

我們需要實現 FileDecorator 類來決定修飾符的行為。這一類必須實現 ILightweightLabelDecorator。用它來擴充 LabelProvider 的想法非常好，因為它可以讓我們只重寫我們感興趣的方法，即 decorate()。

decorate() 的基本實現如 清單 11 所示。

清單 11. 清單 11 decorate() 的簡單實現

public void decorate(Object resource, IDecoration decoration) {decoration.addOverlay(ImageDescriptor.createFromFile(FileDecorator.class, "/icons/sample.gif"), IDecoration.TOP_RIGHT);decoration.addPrefix("My Prefix ");decoration.addSuffix(" My Suffix");}

IDecoration 對象也可用於自訂字型、文本或背景顏色。

圖 4. 圖 4 清單 11 中用來修飾 IResources 的代碼螢幕

decorate() 的第一個參數可以用來篩選我們要修飾的資源。如果我們只想要修飾包含指定標記的資源，就使用如 清單 12 所示的代碼。

清單 12. 清單 12 使用指定標記修飾資源

public void decorate(Object resource, IDecoration decoration) {if(resource instanceof IResource){List<IMarker> markers = MyMarkerFactory.findMarkers((IResource) resource);if (markers.size() > 0) {decoration.addSuffix(" Marker !!");}}}

您已經遵循了本教程的步驟，接下來該做什嗎？

進一步的改進包括：

• 為標記添加可編輯的屬性。允許使用者變更標記的狀態。
• 自動建立和刪除標記。 使用幕後處理作業來自動建立、更新和刪除標記。
• 自訂標籤的 hover。使用進階標記 hover 來支援 HTML 或多媒體內容。

在本教程中，我們使用了 Eclipse 來輕鬆建立和自訂標籤，並執行進階的資源標記工作。 鼓勵開發人員使用這個簡單而又強大的工具來把他們的外掛程式完美地整合到 Eclipse IDE 中。但是，注意，如果此特性用得太廣泛，則對使用者來說會顯得很突兀。此外，將 Eclipse 使用者介面指南考慮在內來維護 Eclipse 的外觀與風格是開發人員的職責，參見 參考資料。

通過 Wiz 發布