11.4 Creating a Standard Plug-in

     

In this example, we're going to be responsible for creating our own plug-in. Like the previous example, this plug-in is going to have its own menu item and toolbar button, but this time, we're going to do the legwork ourselves .

Start by selecting File New Project. In the New Project dialog, select Plug-in Development and Plug-in Project, and click Next. In the next pane, enter the new project's name , org.eclipsebook.ch11.Ch11_02 , and click Next to open the Plug-in Project Structure pane. Click Next again to accept the defaults.

In the Plug-in Code Generators pane, select the Default Plug-In Structure item as shown in Figure 11-11, and click Next.

Figure 11-11. Setting the plug-in's code wizard
figs/ecps_1111.gif

In the following pane, the Simple Plug-in Content pane shown in Figure 11-12, set the provider namewe'll use Eclipse Book in this example. We won't need the convenience methods the wizard can generate for us, so deselect the checkboxes in the "Plug-in code generation options" box. Then click Finish.

Figure 11-12. Setting code options
figs/ecps_1112.gif

This should generate the Ch11_02 plug-in, and open the manifest editor in Eclipse. Click the Source page, which displays the XML in plugin.xml :

 <?xml version="1.0" encoding="UTF-8"?> <plugin    id="org.eclipsebook.ch11.Ch1102"    name="Ch11_02 Plug-in"    version="1.0.0"    provider-name="Eclipse Book"    class="org.eclipsebook.ch11.Ch11_02.Ch11_02Plugin">    <runtime>       <library name="Ch1102.jar"/>    </runtime>    <requires>       <import plugin="org.eclipse.core.resources"/>       <import plugin="org.eclipse.ui"/>    </requires> </plugin> 

That's our new plug-in's manifest. Our goal in this plug-in is to add a new menu item and a button in the toolbar. To make things happen in a plug-in, you define actions and action sets .

An action represents a command that the user can trigger. To implement what goes on in an action, you extend the Action class. You can work with the same Action object in a variety of situations, as when the user selects a menu item or clicks a toolbar buttonthe action object will make the same thing happen in either case. In this way, the same action can be initiated by different user-interface elements.

As you can guess from the name, an action set is a set of actions. You tie actions to user-interface elements like menus and toolbars with an action set (the <actionSet> element in plugin.xml typically contains both <menu> elements and <action> elements). An action is a Java object defining what you want to have happen when the user issues a specific command, and an action set ties actions to user-interface elements.

You create action sets as extensions of the org.eclipse.ui.actionSets extension point, which is how you implement menu items or buttons in a plug-in. You could implement this extension in the XML in plugin.xml directly, but it's much easier to use the manifest editor.

11.4.1 Creating an Action Set

To see how to create an action set to tie a menu and toolbar button to an action, click the Extension tab in the manifest editor and click Add to open the New Extension wizard you see in Figure 11-13. Select the Generic Wizards item in the left box, the Schema-based Extension in the right box, and click Next.

Figure 11-13. The New Extension wizard
figs/ecps_1113.gif

The next pane is the Extension Point Selection pane, which you can see in Figure 11-14. In this case, we want to add support for a menu item and a toolbar button, which is all handled together in our action set, so select the org.eclipse.ui.actionSets extension point, and click Finish.

Figure 11-14. Selecting an extension point
figs/ecps_1114.gif

This adds the base extension we'll need for toolbar and menu support. To create the action set that we'll use, right-click the org.eclipse.ui.actionSets item in the All Extensions box and select the New actionSet item, creating a new action set as you see in Figure 11-15.

Figure 11-15. Creating an action set
figs/ecps_1115.gif

To set the properties of this new action set, select it and, in the Properties view, set the label property to New Action Set and the visible property to true. Using the manifest editor in this way lets you edit the XML in plugin.xml automatically; here's the new XML we've created, indicating that this extension contains an action set:

 <extension       point="org.eclipse.ui.actionSets">    <actionSet          label="New Action Set"          visible="true"          id="org.eclipsebook.ch11.Ch11_02.actionSet1">    </actionSet> </extension> 

11.4.2 Creating a Menu

To create a new menu, right-click New Action Set in the Extensions tab and select New menu. In the Properties view, set the id property of the new menu to newMenu, and the label property to New Menu, as you see in Figure 11-16.

Figure 11-16. Creating a new menu
figs/ecps_1116.gif

To add a menu item here, we'll create a menu separator, which acts as a placeholder and will allow us to add items to this menu at runtime. To add the menu separator, right-click New Menu and select New separator. In the Properties view, set the separator's name property to newGroup, as you see in Figure 11-17.

Figure 11-17. Creating a menu separator
figs/ecps_1117.gif

Our action set has a new menu at this point, and the next step is to tie an action to that menu. If you have multiple menus and multiple toolbar buttons, they could all go into the same action set (which would group your toolbar buttons next to each other in the toolbar).

11.4.3 Creating an Action

Now we'll add a new action to connect Java code to the menu and toolbar handling supported by the action set. To create a new action, right-click the New Action Set item in the All Extensions box and select New action.

To customize this action, we'll create a menu item and toolbar item that will display the message "No worries." To do that, select the new action in the Extensions box. In the Properties view, set the label property to New Action and the toolTip property to No worries. Next, set the menubarPath property to newMenu/newGroup and the toolbarPath property to newGroup.

Now we need to connect this action to Java code. To do that, select the action, New Action, in the All Extensions box, and click the ellipsis (" . . . ") button that appears when you select the class property in the Properties view. This opens the Java Attribute Editor you see in Figure 11-18. Click the Generate a new Java class radio button, enter org.eclipsebook.ch11.Ch11_02 in the Package name box (or click the Browse button and select that package), and name the class NewAction , as you see in the figure. Then click Finish.

Figure 11-18. Creating an action class
figs/ecps_1118.gif

This will create a new <action> element in plugin.xml :

 <action       label="New Action"       tooltip="No worries."       class="org.eclipsebook.ch11.Ch11_02.NewAction"       menubarPath="newMenu/newGroup"       toolbarPath="newGroup"       id="org.eclipsebook.ch11.Ch11_02.action1"> </action> 

In addition, a new Java file, NewAction.java , has been created and added to the project. The framework of the plug-in is in place; all that's left is to write the code that will actually display a message box when the toolbar button or menu item is selected.

11.4.4 Writing the Code

Open NewAction.java now. To display a message box, we'll need an object implementing the Workbench window interface, IWorkbenchWindow . The object we need is passed to the init method in NewAction.java , so begin by creating a private class variable, workbenchWindow , to hold it:

 public class NewAction implements IWorkbenchWindowActionDelegate {  private IWorkbenchWindow workbenchWindow;  .         .         . 

We'll store the workbench window passed to us in the init method in this variable this way:

 public void init(IWorkbenchWindow window)  {  workbenchWindow = window;  } 

Now use this variable and the openInformation method of the MessageDialog class to display a message box with the message "No worries." in the run method:

 public void run(IAction action)  {  MessageDialog.openInformation(   workbenchWindow.getShell( )  ,         "  New Plug-in"  ,         "  No worries.");  } 

Then save all files. That completes the plug-in development; to test this new plug-in, launch the Run-time Workbench. Select Window Customize Perspective as before, and select the box next to the New Action Set item. Doing so should give you the result you see in Figure 11-19, where you can see the default square button icon Eclipse uses for toolbar buttons and the new menu, New Menu.

Figure 11-19. Using the new plug-in
figs/ecps_1119.gif

When you select the New Menu New Action menu item or click the new button, you should see the New Plug-In message box, shown in Figure 11-20. Congratulationsthe new plug-in is doing exactly what it should.

Figure 11-20. The message from the new plug-in
figs/ecps_1120.gif

11.4.5 Automatically Customizing a Perspective

The business of having to customize the perpective every time you launch a new plug-in using Window Customize Perspective is a little cumbersome. There's a way around it if you use the extension point org.eclipse.ui.perspectiveExtensions in plugin.xml , which can add the plug-in to a perspective automatically. It's easy enough to make this change simply by editing the XML in plugin.xml to use the extension point org.eclipse.ui.perspectiveExtensions . For example, to automatically add our plug-in to the Java perspective, you can use the org.eclipse.ui.javaPerspective class like this in plugin.xml :

 <?xml version="1.0" encoding="UTF-8"?> <plugin    id="org.eclipsebook.ch11.Ch1102"    name="Ch11_02 Plug-in"    version="1.0.0"    provider-name="Eclipse Book"    class="org.eclipsebook.ch11.Ch11_02.Ch11_02Plugin">    <runtime>       <library name="Ch1102.jar"/>    </runtime>    <requires>       <import plugin="org.eclipse.core.resources"/>       <import plugin="org.eclipse.ui"/>    </requires>    <extension          point="org.eclipse.ui.actionSets">       <actionSet             label="New Action Set"             visible="true"             id="org.eclipsebook.ch11.Ch11_02.actionSet1">          <menu                label="New Menu"                id="newMenu">             <separator                   name="newGroup">             </separator>          </menu>          <action                label="New Action"                tooltip="No worries."                class="org.eclipsebook.ch11.Ch11_02.NewAction"                menubarPath="newMenu/newGroup"                toolbarPath="newGroup"                id="org.eclipsebook.ch11.Ch11_02.action1">          </action>       </actionSet>    </extension>  <extension   point = "org.eclipse.ui.perspectiveExtensions">   <perspectiveExtension   targetID="org.eclipse.ui.javaPerspective">   <actionSet   id="org.eclipsebook.ch11.Ch11_02.actionSet1">   </actionSet>   </perspectiveExtension>   </extension>  </plugin> 

To automatically add the plug-in to the Resource perspective, use the class org.eclipse.ui.resourcePerspective instead. Save plugin.xml after you make these changes and restart the Run-time Workbench. The plug-in should be installed on startup.



Eclipse
Eclipse
ISBN: 0596006411
EAN: 2147483647
Year: 2006
Pages: 114
Authors: Steve Holzner

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net