| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta name="generator" |
| content="HTML Tidy for Windows (vers 14 February 2006), see www.w3.org" /> |
| <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" /> |
| <meta name="Author" content="OTI Employee, Ketan Padegaonkar" /> |
| |
| <title>Contributing Actions to the Eclipse Workbench</title> |
| <link rel="stylesheet" href="../article.css" type="text/css" /> |
| </head> |
| |
| <body> |
| <h1>Contributing Actions to the Eclipse Workbench</h1> |
| |
| <div class="summary"> |
| <h2>Summary</h2> |
| The Eclipse Platform is an open and extensible platform. This article |
| explains in detail how the Workbench can be extended to add new actions |
| and provides guidance to the plug-in developers on how they can design |
| for extensibility. |
| |
| <div class="author">By Simon Arsenault, OTI</div> |
| <div class="copyright">Copyright © 2001 Object Technology |
| International, Inc.</div> |
| <div class="date">October 18, 2001</div> |
| <div class="author">Updated by <a |
| href="http://ketan.padegaonkar.name">Ketan Padegaonkar</a></div> |
| |
| <div class="copyright">Copyright © 2007 Ketan Padegaonkar</div> |
| <div class="date">January 2, 2007</div> |
| </div> |
| |
| <div class="toc"> |
| <h2>In this article:</h2> |
| |
| <ol> |
| <li><a href="#introduction">Introduction</a></li> |
| |
| <li><a href="#contributionAreas">Areas where you can |
| contribute</a></li> |
| |
| <li>Examples</li> |
| |
| <li style="list-style: none"> |
| <ol> |
| <li><a href="#example1">Example 1: Adding an action to the |
| default text editor</a></li> |
| |
| <li><a href="#example2">Example 2: Adding a sub-menu to the |
| Navigator view</a></li> |
| |
| <li><a href="#example3">Example 3: Adding an action to an |
| object</a></li> |
| |
| <li><a href="#example4">Example 4: Adding actions to the |
| Navigator view's menu and toolbar</a></li> |
| |
| <li><a href="#example5">Example 5: Adding actions to the |
| default text editor's toolbar</a></li> |
| |
| <li><a href="#example6">Example 6: Adding actions to the |
| default text editor's menu bar</a></li> |
| |
| <li><a href="#example7">Example 7: Adding an action set</a></li> |
| |
| <li><a href="#example8">Example 8: Supporting actions on |
| custom editors and views</a></li> |
| </ol> |
| </li> |
| </ol> |
| </div> |
| |
| <div class="content"> |
| <div class="introduction"> |
| <h3 id="introduction">Introduction</h3> |
| The Eclipse Platform allows a plug-in to extend other plug-ins, allowing |
| for a tight integration and therefore a better experience for the end |
| user. This article illustrates how to contribute actions to views and |
| editors of other plug-ins, and allowing for others to contribute to your |
| own custom views and editors. Each example explores in detail the |
| different features available when contributing actions. Once understood, |
| these features can be combined to control the contribution of actions |
| within views and editors.</div> |
| |
| <div class="figure"><img id="contributionAreas" src="images/into_where.jpg" |
| class="screenshot" name="contributionAreas" /></div> |
| The image above shows the many areas where a plug-in can contribute |
| actions: |
| |
| <ul> |
| <li>to the context menu of a view or editor</li> |
| |
| <li>to the local toolbar and pull down menu of a view</li> |
| |
| <li>to the main toolbar and menu bar of the Workbench window</li> |
| </ul> |
| Each different contribution area is examined in this article, with |
| examples showing how to contribute actions to each. |
| |
| <p>In order for an Independent Software Vendor (ISV) to contribute |
| actions to other views and editors, plug-ins need to make their views |
| and editors extensible. This article shows how a plug-in can allow |
| action contributions from other plug-ins.</p> |
| |
| <p>This article assumes a basic understanding of writing a plug-in. |
| For more information on how to write a plug-in for the Eclipse Platform, |
| please read the article from Jim Amsden, "<a |
| href="../Article-Your%20First%20Plug-in/YourFirstPlugin.html">Your |
| First Plug-in</a>".</p> |
| |
| <p>To follow along with the examples in this article, refer to the |
| section <a href="#Running%20the%20examples">running the examples</a>.</p> |
| |
| <h3>Contributing actions to context menus</h3> |
| The ability to add actions to the context menu of a view or editor |
| allows tight integration between plug-ins. For example, the Version and |
| Configuration Management plug-in (VCM) adds a number of new actions to |
| existing views such as the Navigator and Packages views, allowing the |
| user to version manage resources from existing views. To contribute an |
| action to a context menu, the Workbench plug-in (<code>org.eclipse.ui</code>) |
| provides the extension point <code>org.eclipse.ui.popupMenus</code>. |
| There are two types of action contributions. Actions can either be |
| contributed to the context menu of a specific editor or view, or they |
| can be registered against a specific object type. The following three |
| examples will look at each in detail. |
| |
| <h4 id="example1">Example 1: Adding an action to the default text |
| editor</h4> |
| |
| <blockquote>Let's look at how to add a single action to the |
| context menu of the default text editor provided by the Workbench |
| plug-in. <pre> |
| <extension point="org.eclipse.ui.popupMenus"> |
| <img src="images/tag_a.jpg" height="13" width="24" /><viewerContribution |
| id="org.eclipse.ui.articles.action.contribution.popup.editor" |
| <img src="images/tag_b.jpg" height="13" width="24" /> targetID="#TextEditorContext"> |
| <img src="images/tag_c.jpg" height="13" width="24" /> <action |
| id="org.eclipse.ui.articles.action.contribution.editor.action1" |
| label="Editor Action 1" |
| icon="icons/red_dot.gif" |
| <img src="images/tag_d.jpg" height="13" width="24" /> menubarPath="additions" |
| <img src="images/tag_e.jpg" height="13" width="24" /> class="org.eclipse.ui.articles.action.contribution.EditorAction1Delegate"> |
| </action> |
| </viewerContribution> |
| </extension> |
| </pre></blockquote> |
| The XML above declares a contribution to the context menu of a specific |
| editor. These extensions are called viewer extensions (<img |
| src="images/tag_a.jpg" height="13" width="24" />). The term viewer is |
| used to represent both views and editors. |
| |
| <p>The <i>targetID</i> attribute (<img src="images/tag_b.jpg" |
| height="13" width="24" />) specifies the context menu identifier for |
| the target view or editor. The documentation of the plug-in providing |
| the view or editor will list the identifier to use. If none is specified |
| in the documentation, then the context menu is not registered by the |
| plug-in for external action contribution. A view or editor may have more |
| than one context menu.</p> |
| |
| <p>Unfortunately, the default text editor does not follow the <a |
| href="#Developer:%20Allowing%20action%20contribution%20to%20your">guidelines |
| for plug-in developers</a>. The context menu identifier is not part of the |
| default text editor documentation as it should be. Also, the identifier |
| is not fully qualified as recommended by the plug-in developer |
| guidelines.</p> |
| |
| <p>The action to be contributed to the context menu is described |
| next in XML (<img src="images/tag_c.jpg" height="13" width="24" />). |
| The first step is to assign an identifier to the action using the <i>id</i> |
| attribute. The label and icon that will appear in the context menu are |
| given next using the <i>label</i> and <i>icon</i> attributes. The |
| optional <i>icon</i> attribute is specified as a path relative to the |
| plug-in directory.</p> |
| |
| <p>The <i>menubarPath</i> attribute (<img src="images/tag_d.jpg" |
| height="13" width="24" />) specifies the path, starting at the root of |
| the context menu, where this action will be added. In this example, |
| “additions” is the value of the constant <code>org.eclipse.ui.IWorkbenchActionConstants.MB_ADDITIONS</code>. |
| Plug-ins are expected to provide this group once in their context menus |
| indicating the default location where action contributions can be |
| placed. Plug-ins may provide other groups in their context menus where |
| action contributions can be added. In this case, it is recommended that |
| plug-ins document each group. If the <i>menubarPath</i> attribute is not |
| specified, the Workbench will first attempt to add the action in the |
| group “additions”. If the group “additions” does |
| not exist, then the action is added to the end of the context menu.</p> |
| |
| <p>The <i>class</i> attribute (<img src="images/tag_e.jpg" |
| height="13" width="24" />) specifies the Java™ class that will |
| perform the action when the menu item is selected by the user. This |
| class must implement the <code>org.eclipse.ui.IEditorActionDelegate</code> |
| interface if contributing to an editor's context menu or the <code>org.eclipse.ui.IViewActionDelegate</code> |
| interface if contributing to a view's context menu. One <span |
| class="important">very important point</span> to understand about the |
| delegate class is that this class is loaded by the Workbench only when |
| the user selects the menu item for the first time because plug-ins are |
| loaded lazily. This means that the initial enablement logic must be |
| described in XML. Once the delegate class has been loaded by the |
| Workbench, the delegate can control the enabled/disabled state of the |
| action.</p> |
| |
| <p>The interface <code>IEditorActionDelegate</code> allows the |
| action delegate to retarget itself to the active editor. This is |
| important because only one delegate is created for the action and is |
| shared by all instances of the same editor type. The action delegate |
| must implement the method <code>setActiveEditor(IAction action, |
| IEditorPart targetEditor)</code>. When the action is invoked via its <code>run()</code> |
| method, it must act upon the active editor given to the delegate via the |
| last <code>setActiveEditor()</code> method call.</p> |
| |
| <p>The interface <code>IViewActionDelegate</code> allows the action |
| delegate, during initialization, to target itself with the view instance |
| it should work with. The action delegate must implement the method init(<code>IViewPart</code> |
| view). When the action is invoked via its <code>run()</code> method, it |
| must act upon the view passed to <code>init()</code> method.</p> |
| <div class="figure"><img src="images/example1.jpg" class="screenshot" /></div> |
| |
| <p>The image above shows the result of <a |
| href="#Running%20the%20examples">running this example</a>. Notice the |
| "Editor Action 1" is added to the editor's context menu. This is where |
| the “additions” group is located in the default text editor |
| context menu.</p> |
| |
| <h4 id="example2">Example 2: Adding a sub-menu to the Navigator |
| view</h4> |
| |
| <blockquote>Let's look at how to add one action and a |
| sub-menu with two actions to the Navigator view. <pre> |
| <extension point="org.eclipse.ui.popupMenus"> |
| <viewerContribution |
| id="org.eclipse.ui.articles.action.contribution.popup.navigator" |
| <img src="images/tag_a.jpg" height="13" width="24" /> targetID="org.eclipse.ui.views.ResourceNavigator"> |
| <img src="images/tag_b.jpg" height="13" width="24" /> <action |
| id="org.eclipse.ui.articles.action.contribution.navigator.action1" |
| label="View Action 1" |
| icon="icons/red_dot.gif" |
| menubarPath="additions" |
| class="org.eclipse.ui.articles.action.contribution.ViewAction1Delegate" |
| <img src="images/tag_c.jpg" height="13" width="24" /> enablesFor="!"> |
| </action> |
| |
| <img src="images/tag_d.jpg" height="13" width="24" /> <menu |
| id="org.eclipse.ui.articles.action.contribution.navigator.subMenu" |
| label="View Sub Menu" |
| path="additions"> |
| <img src="images/tag_e.jpg" height="13" width="24" /> <separator name="group1"/> |
| </menu> |
| <action |
| id="org.eclipse.ui.articles.action.contribution.navigator.action2" |
| label="View Action 2" |
| icon="icons/red_dot.gif" |
| <img src="images/tag_f.jpg" height="13" width="24" /> menubarPath="org.eclipse.ui.articles.action.contribution.navigator.subMenu/group1" |
| class="org.eclipse.ui.articles.action.contribution.ViewAction2Delegate" |
| <img src="images/tag_c.jpg" height="13" width="24" /> enablesFor="1"> |
| </action> |
| <action |
| id="org.eclipse.ui.articles.action.contribution.navigator.action3" |
| label="View Action 3" |
| icon="icons/red_dot.gif" |
| <img src="images/tag_f.jpg" height="13" width="24" /> menubarPath="org.eclipse.ui.articles.action.contribution.navigator.subMenu/group1" |
| class="org.eclipse.ui.articles.action.contribution.ViewAction3Delegate" |
| <img src="images/tag_c.jpg" height="13" width="24" /> enablesFor="2+"> |
| </action> |
| </viewerContribution> |
| </extension> |
| </pre></blockquote> |
| The XML above declares that a contribution to the context menu of the |
| Navigator view is requested (<img src="images/tag_a.jpg" height="13" |
| width="24" />). The first action contribution (<img |
| src="images/tag_b.jpg" height="13" width="24" />) is then defined just |
| like the previous example. The attributes described in the previous |
| example are skipped to focus on the new attributes and features of this |
| example. |
| |
| <p>Notice the attribute <i>enablesFor</i> in the action definition (<img |
| src="images/tag_c.jpg" height="13" width="24" />). This attribute |
| controls the enabled/disabled state of the action based on the current |
| selection. The current selection is obtained from the selection provider |
| given when the <a |
| href="#Developer:%20Allowing%20action%20contribution%20to%20your">context |
| menu was registered</a> by the plug-in developer. The <i>enablesFor</i> |
| attribute value is the selection count condition which must be met to |
| enable the action. If the condition is not met the action is disabled. |
| If the attribute is left out, the action is enabled for any number of |
| items selected. The following attribute formats are supported:</p> |
| |
| <dl> |
| <dt> </dt> |
| |
| <dd> |
| <table width="45%"> |
| <tr> |
| <td><b><u>Formats</u></b></td> |
| |
| <td><b><u>Description</u></b></td> |
| </tr> |
| |
| <tr> |
| <td><b>!</b></td> |
| |
| <td>0 items selected</td> |
| </tr> |
| |
| <tr> |
| <td><b>?</b></td> |
| |
| <td>0 or 1 items selected</td> |
| </tr> |
| |
| <tr> |
| <td><b>+</b></td> |
| |
| <td>1 or more items selected</td> |
| </tr> |
| |
| <tr> |
| <td><b>multiple, 2+</b></td> |
| |
| <td>2 or more items selected</td> |
| </tr> |
| |
| <tr> |
| <td><b>n</b></td> |
| |
| <td>a precise number of items selected (e.g. 4)</td> |
| </tr> |
| |
| <tr> |
| <td><b>*</b></td> |
| |
| <td>any number of items selected</td> |
| </tr> |
| </table> |
| </dd> |
| </dl> |
| |
| <p>Action enablement is declared in XML because plug-ins are loaded |
| lazily. Until an action is actually invoked by the user, the plug-in is |
| not loaded and the Workbench uses the enablement logic declared in XML. |
| Once a plug-in is loaded, the delegate class is notified of selection |
| changes and can update the enabled/disabled state of the action. Refer |
| to the <code>org.eclipse.ui.IActionDelegate.selectionChanged(IAction |
| action, ISelection selection)</code> method documentation for more details.</p> |
| |
| <p>The <i>menu</i> element (<img src="images/tag_d.jpg" height="13" |
| width="24" />), in this example, specifies the sub menu. The <i>label</i> |
| attribute value is the text displayed in the menu. The <i>path</i> |
| attribute specifies the path, starting at the root of the context menu. |
| This attribute works like the <i>menubarPath</i> attribute of the <i>action</i> |
| element which was discussed in the first example.</p> |
| |
| <p>Within the <i>menu</i> element (<img src="images/tag_d.jpg" |
| height="13" width="24" />), notice that a separator was defined (<img |
| src="images/tag_e.jpg" height="13" width="24" />). A separator serves |
| as a group name into which actions can be added. In this example, the |
| last two actions defined use this separator name in their <i>menubarPath</i> |
| attribute (<img src="images/tag_f.jpg" height="13" width="24" />). This |
| is how the two actions are placed in the sub menu. A menu separator item |
| is added by the Workbench menu manager above and below the group as |
| needed.</p> |
| <div class="figure"><img src="images/example2.jpg" class="screenshot" /></div> |
| |
| <p>The image above shows the result of <a |
| href="#Running%20the%20examples">running this example</a>. Notice the |
| sub menu added to the Navigator's context menu.</p> |
| |
| <p>The order in which the actions are added to the menu and sub menu |
| is in the same order of how they are listed in the plugin.xml file.</p> |
| |
| |
| <h4 id="example3">Example 3: Adding an action to an object</h4> |
| |
| <blockquote>Let's look at how to add a single action to a |
| .java file in a Java project. <pre> |
| <extension point="org.eclipse.ui.popupMenus"> |
| <img src="images/tag_a.jpg" height="13" width="24" /><objectContribution |
| id="org.eclipse.ui.articles.action.contribution.popup.object" |
| <img src="images/tag_b.jpg" height="13" width="24" /> objectClass="org.eclipse.core.resources.IFile" |
| <img src="images/tag_c.jpg" height="13" width="24" /> nameFilter="*.java"> |
| <img src="images/tag_d.jpg" height="13" width="24" /> <filter |
| name="projectNature" |
| value="org.eclipse.jdt.core.javanature"> |
| </filter> |
| <action |
| id="org.eclipse.ui.articles.action.contribution.object.action1" |
| label="Object Action 1" |
| icon="icons/red_dot.gif" |
| menubarPath="additions" |
| <img src="images/tag_e.jpg" height="13" width="24" /> class="org.eclipse.ui.articles.action.contribution.ObjectAction1Delegate"> |
| </action> |
| </objectContribution> |
| </extension> |
| </pre></blockquote> |
| The XML above declares a contribution to <b>every</b> context menu (<img |
| src="images/tag_a.jpg" height="13" width="24" />) but only when the |
| selected objects all match the type specified in the <i>objectClass</i> |
| attribute (<img src="images/tag_b.jpg" height="13" width="24" />). The |
| attribute can be either a fully qualified class or interface name. When |
| the selection is heterogeneous, the contribution will be applied if it |
| is registered against a common type of the selection. If a direct match |
| is not possible, matching against super classes and super interfaces |
| will be attempted. The action contribution is dependent on the selection |
| only containing objects of the specified type, and is not limited to one |
| view or editor's context menu. |
| |
| <p>For example, if the file "f1.java" and the project "Java Project" |
| are selected in the Navigator when the context menu is shown for that |
| view, then the action contribution defined by the XML above would be |
| excluded because the object "Java Project" is of type <code>IProject</code> |
| not <code>IFile</code>, and <code>IFile</code> is not a super interface |
| of <code>IProject</code>. However, if the <i>objectClass</i> attribute |
| value in the XML above was <code>org.eclipse.core.resources.IResource</code>, |
| then the action contribution would be included because IResource is a |
| super interface of both IFile ("f1.java") and IProject ("Java Project"), |
| neglecting for the moment the <i>nameFilter</i> attribute.</p> |
| |
| <p>The <i>nameFilter</i> attribute (<img src="images/tag_c.jpg" |
| height="13" width="24" />) is used to further constrain the selection |
| to which this action will apply. In this example, only <code>IFile</code>s |
| that end with the .java extension are considered. The value of this |
| attribute is compared to the <code>org.eclipse.ui.model.IWorkbenchAdapter.getLabel()</code> |
| method result for each object in the selection. If the object does not |
| have an <code>IWorkbenchAdapter</code>, then the object's toString() |
| method is used. If this attribute is not specified, then no filtering is |
| done on the object's name.</p> |
| |
| <p>The <i>filter</i> element (<img src="images/tag_d.jpg" |
| height="13" width="24" />) provides another way of controlling the |
| enablement criteria of an action. These are name/value pairs of |
| attributes for the objects in the selection. The attributes which apply |
| to the selection are type-specific, so the Workbench delegates filtering |
| at this level to the actual selection (see <code>IActionFilter</code> |
| javadoc). In this example, the object attribute name, "projectNature", |
| is defined on <code>IResourceActionFilter</code> and is applicable to |
| all <code>IResources</code>. Therefore, the action contribution will |
| only happen if the <code>IProject</code> of each object in the selection |
| has a Java nature. Refer to the documentation on IActionFilter and its |
| sub-interfaces for a list and description of other named attributes. For |
| more information about project natures, refer to the documentation on <code>org.eclipse.core.resources.IProjectNature</code> |
| interface.</p> |
| |
| <p>For object contributions, the <i>class</i> attribute (<img |
| src="images/tag_e.jpg" height="13" width="24" />) of the <i>action</i> |
| element is the name of a Java class that implements the <code>org.eclipse.ui.IObjectActionDelegate</code> |
| interface. The interface <code>IObjectActionDelegate</code> allows the |
| action delegate to retarget itself to the active part. This is important |
| because only one delegate is created for the action and is shared by all |
| instances of <code>IWorkbenchPart</code>. The action delegate must |
| implement the method <code>setActivePart(IAction action, |
| IWorkbenchPart targetPart).</code> When the action is invoked via its <code>run()</code> |
| method, it must act upon the active part given to the delegate via the |
| last <code>setActivePart()</code> method call.</p> |
| <div class="figure"><img src="images/example3.jpg" class="screenshot" /></div> |
| |
| <p>The image above shows the result of <a |
| href="#Running%20the%20examples">running this example</a>. Notice the |
| object action contribution is added to the Navigator's context menu |
| because a .java file within a Java project is selected.</p> |
| |
| <h4><a name="Developer: Allowing action contribution to your"></a>Developer |
| Guideline: Supporting action contributions in your own context menus</h4> |
| Within the Workbench, action contributions to a context menu is only |
| possible when the menu is made known to the Workbench. This is a |
| voluntary process, but plug-ins are encouraged to expose their menus so |
| that ISVs may extend them. This increases the overall extensability and |
| integration of the platform. |
| |
| <p>Each context menu should be registered with the Workbench. This |
| is accomplished by calling either <code>org.eclipse.ui.IWorkbenchPartSite.registerContextMenu(MenuManager |
| menuManager, ISelectionProvider selectionProvider)</code> or <code>org.eclipse.ui.IWorkbenchPartSite.registerContextMenu(String |
| menuId, MenuManager menuManager, ISelectionProvider selectionProvider)</code>. |
| If a view or editor has more than one context menu to expose, then each |
| one needs to be registered. Once the context menu is registered, the |
| Workbench will automatically insert any action contributions which exist |
| into the menu.</p> |
| |
| <p>As part of the context menu registration, a unique identifier for |
| each context menu is required to avoid conflicts in the Workbench global |
| registry of context menus. For consistency across all parts, the |
| following strategy should be adopted by all plug-ins registering a |
| context menu:</p> |
| |
| <ul> |
| <li>If the view or editor has only one context menu, it should be |
| given the same identifier as the view or editor's identifier. For |
| convenience, publishers can call <code>registerContextMenu(MenuManager, |
| ISelectionProvider)</code> on <code>IWorkbenchPartSite</code>.</li> |
| |
| <li>If the view or editor has more than one context menu, each |
| should be given a unique identifier whose prefix is the identifier of |
| the view or editor. For example, an editor, with identifier <code>com.xyz.bestEditor</code>, |
| has two context menus. The first context menu identifier would be <code>org.xyz.bestEditor.menu1</code> |
| and the second context menu identifier would be <code>com.xyz.bestEditor.menu2</code>. |
| Register each context menu by calling <code>registerContextMenu(String, |
| MenuManager, ISelectionProvider)</code> on <code>IWorkbenchPartSite</code>.</li> |
| </ul> |
| All context menu identifiers should be published within the javadoc of |
| the view or editor. This makes it easier for ISVs to determine the menu |
| identifier for a particular part and define action contributions. These |
| identifiers are used as the <i>targetID</i> attribute value in action |
| contributions. |
| |
| <p>Publishers of context menus should include the standard insertion |
| point identifier <code>IWorkbenchActionConstants.MB_ADDITIONS</code>. |
| This default reference point is used for insertion of actions |
| contributed by ISVs. The insertion point is defined by adding a |
| GroupMarker to the menu at an appropriate location for insertion. Other |
| insertion points can be defined and published within the javadoc of the |
| view or editor. This is strongly recommended to allow ISVs better |
| control of where the action will be inserted within the context menu.</p> |
| |
| <p>A plug-in developer of an object that can be part of a selection |
| in a context menu can implement the <code>org.eclipse.ui.IActionFilter</code> |
| interface. This is a filtering strategy which can perform type-specific |
| filtering based on name/value pairs. This permits an ISV to use these |
| name/value pairs within the <i>filter</i> element in XML to further |
| restrict which objects the action contribution applies to. The Workbench |
| will retrieve the filter for the selection by testing to see if it |
| implements IActionFilter. If that fails, the Workbench will ask for a |
| filter through the IAdaptable mechanism.</p> |
| |
| <h3>Contributing actions to a view's menu or toolbar</h3> |
| |
| A view has a local pull down menu and a toolbar which is initially |
| populated by the view itself. Other plug-ins can contribute actions to |
| this menu and toolbar by using the <code>org.eclipse.ui.viewActions</code> |
| extension point. |
| |
| |
| <h4 id="example4">Example 4: Adding actions to the Navigator view's |
| menu and toolbar</h4> |
| |
| <blockquote>Let's look at how to contribute a different |
| action to both the pull down menu and toolbar of the Navigator view. <pre> |
| <extension point="org.eclipse.ui.viewActions"> |
| <img src="images/tag_a.jpg" height="13" width="24" /><viewContribution |
| id="org.eclipse.ui.articles.action.contribution.view" |
| <img src="images/tag_b.jpg" height="13" width="24" /> targetID="org.eclipse.ui.views.ResourceNavigator"> |
| <img src="images/tag_c.jpg" height="13" width="24" /> <action |
| id="org.eclipse.ui.articles.action.contribution.view.action1" |
| label="View Action 1" |
| icon="icons/red_dot.gif" |
| tooltip="Tooltip for View Action 1" |
| <img src="images/tag_d.jpg" height="13" width="24" /> menubarPath="additions" |
| class="org.eclipse.ui.articles.action.contribution.ViewAction1Delegate" |
| enablesFor="*"> |
| </action> |
| <img src="images/tag_e.jpg" height="13" width="24" /> <action |
| id="org.eclipse.ui.articles.action.contribution.view.action2" |
| label="View Action 2" |
| icon="icons/red_dot.gif" |
| tooltip="Tooltip for View Action 2" |
| <img src="images/tag_f.jpg" height="13" width="24" /> toolbarPath="group1" |
| class="org.eclipse.ui.articles.action.contribution.ViewAction2Delegate" |
| enablesFor="*"> |
| <img src="images/tag_g.jpg" height="13" width="24" /> <selection |
| class="org.eclipse.core.resources.IFile" |
| name="*.java"> |
| </selection> |
| </action> |
| </viewContribution> |
| </extension> |
| </pre></blockquote> |
| The above XML informs the Workbench that a plug-in wants to contribute |
| to the Navigator's pull down menu and toolbar (<img |
| src="images/tag_a.jpg" height="13" width="24" />). In this example, |
| the <i>targetID</i> attribute (<img src="images/tag_b.jpg" height="13" |
| width="24" />) refers to the Navigator view identifier. |
| |
| <p>The first <i>action</i> element (<img src="images/tag_c.jpg" |
| height="13" width="24" />) should look familiar by now, with the same |
| attributes covered in previous examples. The value of the <i>menubarPath</i> |
| attribute (<img src="images/tag_d.jpg" height="13" width="24" />) is |
| the same as IWorkbenchActionConstants.MB_ADDITIONS constant, which is |
| the default group that contributors add actions to. Though not shown in |
| this example, it is possible to add a sub-menu to the view's pull down |
| menu simply by defining a <i>menu</i> element. Refer to the previous |
| example on <a |
| href="#Example:%20Adding%20sub-menu%20to%20the%20Navigator">adding |
| sub-menu to a context menu</a> for more details.</p> |
| |
| <p>The second <i>action</i> element (<img src="images/tag_e.jpg" |
| height="13" width="24" />) is only slightly different than the first |
| one. Instead of adding the action to the pull down menu (using the <i>menubarPath</i> |
| attribute), the action is added to the view's toolbar (<img |
| src="images/tag_f.jpg" height="13" width="24" />). The value of the <i>toolbarPath</i> |
| attribute specifies the group into which the action should be added. If |
| the group specified does not exist, then it is created at the end of the |
| toolbar and a separator is added if required. Views may publish groups |
| to which a plug-in can add actions inside the toolbar. In the case of |
| the Navigator view's toolbar, it does not publish any groups. Unlike a |
| menu which has the default IWorkbenchActionConstants.MB_ADDITIONS group, |
| a toolbar is not required to provide one.</p> |
| |
| <p>The <i>selection</i> element (<img src="images/tag_g.jpg" |
| height="13" width="24" />) can further constrain the selection to |
| which this action applies. The <i>class</i> attribute specifies the |
| selection object type that must be met for the action to be enabled. In |
| this example, the action is only enabled if all the objects within the |
| selection implement the IFile interface. The <i>name</i> attribute |
| specifies a wildcard match against each object in the selection. The |
| value of this attribute is compared to the <code>org.eclipse.ui.model.IWorkbenchAdapter.getLabel()</code> |
| method result for each object in the selection. In this example, the |
| action is only enabled if all the objects in the selection end with the |
| .java extension. The <i>selection</i> element is ignored by the |
| Workbench if the <i>enablesFor</i> attribute is not specified.</p> |
| <div class="figure"><img src="images/example4.jpg" class="screenshot" /></div> |
| |
| <p>The image above shows the result of <a |
| href="#Running%20the%20examples">running this example</a>. Notice the |
| action added to the Navigator's pull down menu. The action added in the |
| toolbar is enabled because the current selection contains .java files.</p> |
| |
| <h4>Developer Guideline: Supporting action contributions in your |
| own views</h4> |
| Developers of a view should include the standard insertion point |
| identifier <code>IWorkbenchActionConstants.MB_ADDITIONS</code> in the |
| view's pull down menu. This reference point will be used for insertion |
| of actions contributed by ISVs. The insertion point is defined by adding |
| a GroupMarker to the menu at an appropriate location for insertion. |
| Other insertion points can be defined and published within the javadoc |
| of the view. This is strongly recommended to allow ISVs better control |
| of where the action will be inserted within the pull down menu. |
| |
| |
| <h3>Contributing actions to an editor's menu or toolbar</h3> |
| |
| An editor will contribute its actions to the main menu bar and toolbar |
| of the Workbench window. Another plug-in can contribute actions for a |
| particular editor by using the <code>org.eclipse.ui.editorActions</code> |
| extension point. Each action extension is created and shared by all |
| instances of the same editor type. |
| |
| |
| <h4 id="example5">Example 5: Adding actions to the default text |
| editor's toolbar</h4> |
| |
| <blockquote>Let's look at how to contribute two actions to |
| the toolbar of the default text editor. <pre> |
| <extension point="org.eclipse.ui.editorActions"> |
| <img src="images/tag_a.jpg" height="13" width="24" /><editorContribution |
| id="org.eclipse.ui.articles.action.contribution.editor" |
| <img src="images/tag_b.jpg" height="13" width="24" /> targetID="org.eclipse.ui.DefaultTextEditor"> |
| <img src="images/tag_c.jpg" height="13" width="24" /> <action |
| id="org.eclipse.ui.articles.action.contribution.editor.action1" |
| label="Editor Action 1" |
| icon="icons/red_dot.gif" |
| tooltip="Tooltip for Editor Action 1" |
| <img src="images/tag_d.jpg" height="13" width="24" /> toolbarPath="Normal/additions" |
| class="org.eclipse.ui.articles.action.contribution.EditorAction1Delegate"> |
| </action> |
| <img src="images/tag_e.jpg" height="13" width="24" /> <action |
| id="org.eclipse.ui.articles.action.contribution.editor.action2" |
| label="Editor Action 2" |
| icon="icons/red_dot.gif" |
| tooltip="Tooltip for Editor Action 2" |
| helpContextId="org.eclipse.ui.articles.action.contribution.editor.action2" |
| <img src="images/tag_f.jpg" height="13" width="24" /> toolbarPath="Normal/save.ext" |
| class="org.eclipse.ui.articles.action.contribution.EditorAction2Delegate"> |
| </action> |
| </editorContribution> |
| </extension> |
| </pre></blockquote> |
| As with previous examples, the first few lines instruct the Workbench |
| that actions are being contributed to the default text editor (<img |
| src="images/tag_a.jpg" height="13" width="24" /> and <img |
| src="images/tag_b.jpg" height="13" width="24" />). In this example, |
| two actions are added to the toolbar of the editor. |
| |
| <p>The toolbarPath attribute value (<img src="images/tag_d.jpg" |
| height="13" width="24" /> and <img src="images/tag_f.jpg" |
| height="13" width="24" />) is different than previous examples in that |
| the first segment of the path represents the toolbar identifier, while |
| the second segment represents the group within the toolbar. The toolbar |
| identifier allows the plug-in to determine which toolbar the action is |
| added to. Currently in the Workbench, only one toolbar is supported and |
| its identifier is "Normal". If the group does not exist, then it is <span |
| class="important">not</span> created within the specified toolbar, and |
| the action is <span class="important">not</span> added to the specified |
| toolbar. Valid toolbar groups are listed in the documentation of the <code>IWorkbenchActionConstants</code> |
| interface and the plugin providing the target editor.</p> |
| |
| <p>The first action (<img src="images/tag_c.jpg" height="13" |
| width="24" />) is added to the default group called <code>IWorkbenchActionConstants.MB_ADDITIONS</code> |
| using the <i>toolbarPath</i> attribute (<img src="images/tag_d.jpg" |
| height="13" width="24" />). The second action (<img |
| src="images/tag_e.jpg" height="13" width="24" />) is being added to |
| the group called <code>IWorkbenchActionConstants.SAVE_EXT</code> using |
| the <i>toolbarPath</i> attribute (<img src="images/tag_f.jpg" |
| height="13" width="24" />). Refer to the interface <code>IWorkbenchActionConstants</code> |
| for a list of other groups provided by the Workbench window main |
| toolbar.</p> |
| <div class="figure"><img src="images/example5.jpg" class="screenshot" /></div> |
| |
| <p>The image above shows the result of <a |
| href="#Running%20the%20examples">running this example</a>. Notice the |
| action next to the save tool items and the action added at the end of |
| the toolbar.</p> |
| |
| |
| <h4 id="example6">Example 6: Adding actions to the default text |
| editor's menu bar</h4> |
| |
| <blockquote>Let's look at how to contribute to the default |
| text editor's menu bar the following: |
| |
| <ul> |
| <li>an action to the File menu,</li> |
| |
| <li>a sub-menu with two actions to the Edit menu,</li> |
| |
| <li>a new top level menu with one action.</li> |
| </ul> |
| <pre> |
| <extension point="org.eclipse.ui.editorActions"> |
| <editorContribution |
| id="org.eclipse.ui.articles.action.contribution.editor2" |
| <img src="images/tag_a.jpg" height="13" width="24" /> targetID="org.eclipse.ui.DefaultTextEditor"> |
| <action |
| id="org.eclipse.ui.articles.action.contribution.editor.action1" |
| label="Editor Action 1" |
| icon="icons/red_dot.gif" |
| tooltip="Tooltip for Editor Action 1" |
| <img src="images/tag_b.jpg" height="13" width="24" /> menubarPath="file/save.ext" |
| class="org.eclipse.ui.articles.action.contribution.EditorAction1Delegate"> |
| </action> |
| |
| <img src="images/tag_c.jpg" height="13" width="24" /> <menu |
| id="org.eclipse.ui.articles.action.contribution.editor.subMenu" |
| label="Editor Sub Menu" |
| path="edit/additions"> |
| <separator name="group1"/> |
| </menu> |
| <action |
| id="org.eclipse.ui.articles.action.contribution.editor.action2" |
| label="Editor Action 2" |
| icon="icons/red_dot.gif" |
| tooltip="Tooltip for Editor Action 2" |
| <img src="images/tag_d.jpg" height="13" width="24" /> menubarPath="org.eclipse.ui.articles.action.contribution.editor.subMenu/group1" |
| class="org.eclipse.ui.articles.action.contribution.EditorAction2Delegate"> |
| </action> |
| <action |
| id="org.eclipse.ui.articles.action.contribution.editor.action3" |
| label="Editor Action 3" |
| icon="icons/red_dot.gif" |
| tooltip="Tooltip for Editor Action 3" |
| <img src="images/tag_e.jpg" height="13" width="24" /> menubarPath="org.eclipse.ui.articles.action.contribution.editor.subMenu/group1" |
| class="org.eclipse.ui.articles.action.contribution.EditorAction3Delegate"> |
| </action> |
| |
| <img src="images/tag_f.jpg" height="13" width="24" /> <menu |
| id="org.eclipse.ui.articles.action.contribution.editor.topLevelMenu" |
| label="EditorTopLevelMenu" |
| path="additions"> |
| <separator name="group1"/> |
| </menu> |
| <action |
| id="org.eclipse.ui.articles.action.contribution.editor.action4" |
| label="Editor Action 4" |
| icon="icons/red_dot.gif" |
| tooltip="Tooltip for Editor Action 4" |
| <img src="images/tag_g.jpg" height="13" width="24" /> menubarPath="org.eclipse.ui.articles.action.contribution.editor.topLevelMenu/group1" |
| class="org.eclipse.ui.articles.action.contribution.EditorAction4Delegate"> |
| </action> |
| </editorContribution> |
| </extension> |
| </pre></blockquote> |
| As in previous examples, the <i>targetID</i> attribute value (<img |
| src="images/tag_a.jpg" height="13" width="24" />) lets the Workbench |
| know that the actions are being added to the default text editor. The |
| first action declaration specifies a <i>menubarPath</i> attribute (<img |
| src="images/tag_b.jpg" height="13" width="24" />). The value comes |
| from <code>IWorkbenchActionConstants.M_FILE</code> and <code>IWorkbenchActionConstants.SAVE_EXT</code> |
| constants. This tells the Workbench to add the action to the save group |
| of the File menu. |
| |
| <p>Next a sub-menu is defined in the Edit menu (<img |
| src="images/tag_c.jpg" height="13" width="24" />). The <i>path</i> |
| attribute of the <i>menu</i> element is made up from the <code>IWorkbenchActionConstants.M_EDIT</code> |
| and <code>IWorkbenchActionConstants.MB_ADDITIONS</code> constants. The |
| following two action declarations have a <i>menubarPath</i> attribute (<img |
| src="images/tag_d.jpg" height="13" width="24" /> and <img |
| src="images/tag_e.jpg" height="13" width="24" />) which specifies the |
| path to the group created for the sub menu (<img src="images/tag_c.jpg" |
| height="13" width="24" />).</p> |
| |
| <p>In the Workbench's main menu bar, there is a problem with |
| contributing actions to a contributed sub-menu. These sub-menu items are |
| lost by the Workbench, so the sub-menu is empty and therefore is visible |
| but disabled. This sub-menu problem is only for editor menu |
| contributions and action set contributions. This is why the sub-menu |
| contribution to the Edit menu is disabled.</p> |
| |
| <p>The last part of the XML is used to define a new top level menu |
| to the left of the Window menu (<img src="images/tag_f.jpg" height="13" |
| width="24" />). The <i>path</i> attribute of the <i>menu</i> element |
| comes from the <code>IWorkbenchActionConstants.MB_ADDITIONS</code> |
| constant. This is the default group plug-ins use to add top level menus |
| to the menu bar. These new menus are always added to the left of the |
| Window menu.</p> |
| |
| <p>The last <i>action</i> element has a <i>menubarPath</i> attribute |
| (<img src="images/tag_g.jpg" height="13" width="24" />) which specifies |
| the path to the group created for the top level menu (<img |
| src="images/tag_f.jpg" height="13" width="24" />). That is the |
| location where the action is added by the Workbench.</p> |
| <div class="figure"><img src="images/example6.jpg" class="screenshot" /></div> |
| |
| <p>The image above shows the result of <a |
| href="#Running%20the%20examples">running this example</a>. Notice the |
| action below the save menu items in the File menu and the new top level |
| menu.</p> |
| |
| <p>When contributing to the Perspective or Project menu, the path |
| name is not the same as the menu name. The constant <code>IWorkbenchActionConstants.M_VIEW</code> |
| is used to represent the path to the Perspective menu and the constant <code>IWorkbenchActionConstants.M_WORKBENCH</code> |
| is used to represent the path to the Project menu. This is for |
| historical reasons; these menus were renamed after the constants were |
| defined as API.</p> |
| |
| <h4>Developer Guideline: Supporting action contributions in your |
| own editors</h4> |
| Publishers of an editor should include the standard insertion point |
| identifier <code>IWorkbenchActionConstants.MB_ADDITIONS</code> in all |
| top level menus added by the editor. This reference point is used for |
| insertion of actions contributed by ISVs. The insertion point is defined |
| by adding a GroupMarker to the menu at an appropriate location for |
| insertion. Other insertion points can be defined and published within |
| the javadoc of the editor. This is strongly recommended to allow ISVs |
| better control of where the action is inserted within the menu bar. |
| |
| |
| <h3>Contributing actions via action sets</h3> |
| |
| |
| An action set is a mechanism that allows a plug-in to contribute menus, |
| menu items, and toolbar items to the main menu bar and toolbar of the |
| Workbench window. It is important to understand what action sets are |
| meant to be used for. An action set should contribute common actions |
| which are not specific to any particular view or editor. Typically, an |
| action set would include creation actions, global actions, etc. It is |
| not a mechanism for a view to "promote" its actions to the main menu bar |
| and toolbar. |
| |
| <p>The user can choose which action sets are visible. The goal is to |
| let users customize the Workbench environment to suit their needs and |
| override the assumptions made by the plug-in about which actions are |
| appropriate. Plug-in developers of views and editors are encouraged to |
| define important actions locally within their own menu and toolbar so |
| that they are available even when the action set is not visible.</p> |
| |
| <p>A plug-in uses the <code>org.eclipse.ui.actionSets</code> |
| extension point to define an action set. These actions appear in the |
| Workbench window by user preference. See the customize perspective |
| dialog by selecting the menu item Perspective->Customize... and then |
| expanding the Other category.</p> |
| |
| |
| <h4 id="example7">Example 7: Adding an action set</h4> |
| |
| <blockquote>Let's look at how to add an action set which |
| contains two toolbar items. <pre> |
| <extension point="org.eclipse.ui.actionSets"> |
| <actionSet |
| id="org.eclipse.ui.articles.action.contribution.set" |
| <img src="images/tag_a.jpg" height="13" width="24" /> label="Action Set 1" |
| <img src="images/tag_b.jpg" height="13" width="24" /> visible="false"> |
| <action |
| id="org.eclipse.ui.articles.action.contribution.set.action1" |
| label="Set Action 1" |
| icon="icons/red_dot.gif" |
| tooltip="Tooltip for Set Action 1" |
| <img src="images/tag_c.jpg" height="13" width="24" /> toolbarPath="Normal/additions" |
| class="org.eclipse.ui.articles.action.contribution.SetAction1Delegate"> |
| </action> |
| <action |
| id="org.eclipse.ui.articles.action.contribution.set.action2" |
| label="Set Action 2" |
| icon="icons/red_dot.gif" |
| tooltip="Tooltip for Set Action 2" |
| <img src="images/tag_d.jpg" height="13" width="24" /> toolbarPath="Normal/additions" |
| <img src="images/tag_e.jpg" height="13" width="24" /> style="pulldown" |
| <img src="images/tag_f.jpg" height="13" width="24" /> class="org.eclipse.ui.articles.action.contribution.SetAction2Delegate"> |
| </action> |
| </actionSet> |
| </extension> |
| </pre></blockquote> |
| The attribute <i>label</i> (<img src="images/tag_a.jpg" height="13" |
| width="24" />) specifies the name of the group of actions. This text |
| appears in the customize perspective dialog box |
| (Perspective->Customize...) by expanding the "Other" tree item. |
| |
| <p>The attribute <i>visible</i> (<img src="images/tag_b.jpg" |
| height="13" width="24" />) is optional and specifies whether this |
| action set should be initially made visible when any perspective is |
| open. This option will only be honoured when the user opens a new |
| perspective which has not been customized. The user can override this |
| setting by customizing the perspective. By default, the value of this |
| attribute is false. Caution should be taken when enabling this attribute |
| so as not to abuse it. If every plug-in enables this attribute, then all |
| perspectives will be cluttered with these action sets. A better approach |
| is for the plug-in to specify which perspective(s) should show its |
| action sets by using the extension point <code>org.eclipse.ui.perspectiveExtensions</code>. |
| Please refer to "Extending an Existing Perspective" in Dave Springgay's |
| article "<a |
| href="http://www.eclipsecorner.org/articles/using-perspectives/PerspectiveArticle.html">Using |
| Perspectives in the Eclipse UI</a>" for more details.</p> |
| |
| <p>The definition of each action looks the same as in previous |
| examples. However, the <i>toolbarPath</i> attribute (<img |
| src="images/tag_c.jpg" height="13" width="24" /> and <img |
| src="images/tag_d.jpg" height="13" width="24" />) value is different |
| in that the first segment of the path represents the toolbar identifier, |
| while the second segment represents the group within the toolbar. The |
| toolbar identifier allows the plug-in to determine which toolbar the |
| action is added to. Currently in the Workbench, only one toolbar is |
| supported and its identifier is "Normal". If the group does not exist, |
| then it is created within the specified toolbar.</p> |
| |
| <p>The second action definition introduces the optional <i>style</i> |
| attribute (<img src="images/tag_e.jpg" height="13" width="24" />). When |
| set to "pulldown", the tool item has an optional pull down menu. The |
| tool item has the same look as the tool item "Open The New Wizard" |
| provided by the Workbench window. This attribute is ignored for menu |
| item contributions.</p> |
| |
| <p>The <i>class</i> attribute (<img src="images/tag_f.jpg" |
| height="13" width="24" />) specifies the Java class that is loaded to |
| perform the action invoked by the user. This class must implement <code>org.eclipse.ui.IWorkbenchWindowActionDelegate</code> |
| interface if the <i>style</i> attribute is "push", "radio", or "toggle"; |
| or <code>org.eclipse.ui.IWorkbenchWindowPulldownDelegate</code> |
| interface if the <i>style</i> attribute is "pulldown". This delegate |
| class can control the enabled/disabled state of the action when the |
| selection changes, but only once the plug-in is loaded. Until then, the |
| enabled/disabled state of the action is controlled by other XML |
| attributes like <i>enablesFor</i> and <i>selection</i>.</p> |
| <div class="figure"><img src="images/example7.jpg" class="screenshot" /></div> |
| |
| <p>The image above shows the result of <a |
| href="#Running%20the%20examples">running this example</a>. Notice the |
| two actions added at the end of the toolbar, with one having a drop down |
| menu option. To show this action set in the current perspective, select |
| the menu item Perspective->Customize..., expand the Other category, |
| and check the option "Action Set 1".</p> |
| |
| |
| <h4 id="example8">Example 8: Supporting actions on custom editors |
| and views</h4> |
| |
| <blockquote>Let's look at how to add a single action to the |
| context menu of your own editor or view <pre> |
| <extension point="org.eclipse.ui.popupMenus"> |
| <viewerContribution |
| id="org.eclipse.ui.articles.action.contribution.popup.xmleditor" |
| <img src="images/tag_a.jpg" height="13" width="24" /> targetID="org.eclipse.articles.xmleditor.editors.XMLEditor.context"> |
| <action |
| id="org.eclipse.ui.articles.action.contribution.editor.xmltextaction1" |
| label="XML Text Editor Action" |
| icon="icons/red_dot.gif" |
| menubarPath="additions" |
| class="org.eclipse.ui.articles.action.contribution.EditorAction1Delegate"> |
| </action> |
| </viewerContribution> |
| </extension> |
| </pre></blockquote> |
| This is very similar to <a href="#example1">Example 1</a> covered above; |
| and only differences from <a href="#example1">Example 1</a> are |
| highlighted here. This example uses the XML editor created using the |
| standard eclipse wizard: |
| |
| <ul> |
| <li>File > New > Project > Plug-in Project</li> |
| |
| <li>Project Name: org.eclipse.articles.xmlEditor, click "Next"</li> |
| |
| <li>On the "Templates page", select "Plug-in with an editor" (this |
| creates a sample XML editor)</li> |
| |
| <li>Accept all defaults and click to the finish.</li> |
| </ul> |
| |
| <p>The <i>targetID</i> attribute (<img src="images/tag_a.jpg" |
| height="13" width="24" />) specifies the context menu identifier for |
| the target view or editor (<code>XMLEditor.EDITOR_CONTEXT</code>). The |
| documentation of the plug-in providing the view or editor will list the |
| identifier to use. If none is specified in the documentation, then the |
| context menu is not registered by the plug-in for external action |
| contribution. A view or editor may have more than one context menu.</p> |
| |
| <p>The code below shows the additions that you have to make to the |
| XMLEditor created using the standard template.</p> |
| <blockquote><pre> |
| public class XMLEditor extends TextEditor { |
| |
| /** The ID of this editor as defined in plugin.xml */ |
| public static final String EDITOR_ID = "org.eclipse.articles.xmleditor.editors.XMLEditor"; |
| |
| /** The ID of the editor context menu */ |
| public static final String EDITOR_CONTEXT = EDITOR_ID + ".context"; |
| |
| /** The ID of the editor ruler context menu */ |
| public static final String RULER_CONTEXT = EDITOR_CONTEXT + ".ruler"; |
| |
| protected void initializeEditor() { |
| super.initializeEditor(); |
| setEditorContextMenuId(EDITOR_CONTEXT); |
| setRulerContextMenuId(RULER_CONTEXT); |
| } |
| ... |
| } |
| </pre></blockquote> |
| <div class="figure"><img src="images/example8.jpg" class="screenshot" /></div> |
| |
| <p>The image above shows the result of <a |
| href="#Running%20the%20examples">running this example</a>. Notice the |
| "XML Text Editor Action" is added to the XML editor's context menu. This |
| is where the “additions” group is located in the default |
| text editor context menu.</p> |
| |
| |
| <h3>Conclusion</h3> |
| This article has covered the extension points that a plug-in may use to |
| contribute actions to the Workbench. The best way to learn more about |
| action contributions is to take the examples and experiment with them. |
| Plug-in developers should pay special attention to the recommendations |
| made here so that ISVs can contribute actions and achieve a high level |
| of integration. More information is available in the Platform Plug-in |
| Developer Guide from the Help perspective, and in the <code>org.eclipse.ui |
| extension</code> points documentation from the Platform Plug-in Developer |
| Guide, expand Reference->Extension Points Reference->Workbench. |
| |
| <h3><a name="Running the examples"></a>Running the examples</h3> |
| The file "<a href="source/action_contribution_examples.zip">action_contribution_examples.zip</a>" |
| contains the complete source code for all the examples in this article. |
| Extract the content of the ZIP file into the Eclipse "plugins" directory |
| to install the action contribution example plug-in. Then edit the |
| plugin.xml file to uncomment the example to be run.</div> |
| |
| <div class="notices"> |
| <h2>Notices</h2> |
| Java and all Java-based trademarks and logos are trademarks or |
| registered trademarks of Sun Microsystems, Inc. in the United States, |
| other countries, or both.</div> |
| </body> |
| </html> |