1 Eclipse Platform Plug-in developper Guide PDG HowTos

2 Plugging into the workbench l The workbench is the cockpit for navigating all of the function provided by plug-ins. l By using the workbench, we can navigate resources and we can view and edit the content and properties of these resources.

3 Workbench

4 workbench

5 l we use the term workbench for referring to the workbench window (IWorkbenchWindow). l The workbench window is the top-level window in a workbench. »It is the frame that holds the menu bar, tool bar, status line, short cut bar, and pages. »In general, you don't need to program to the workbench window. You just want to know that it's there. l Note: You can open multiple workbench windows; however each workbench window is a self-contained world of editors and views, so we'll just focus on a single workbench window. l From the user's point of view, a workbench contains views and editors. There are a few other classes used to implement the workbench window.

6 Page l Inside the workbench window, you'll find one page (IWorkbenchPage) that in turn contains parts. l Pages are an implementation mechanism for grouping parts. You typically don't need to program to the page, but you'll see it in the context of programming and debugging.

7 Basic workbench extension points

8 org.eclipse.ui.views l A view is a workbench part that can navigate a hierarchy of information or display properties for an object. l Only one instance of any given view is open in a workbench page. l When the user makes selections or other changes in a view, those changes are immediately reflected in the workbench. l Views are often provided to support a corresponding editor. »outline view shows a structured view of the information in an editor. »properties view shows the properties of an object that is currently being edited.

9 views extension point l The extension point org.eclipse.ui.views allows plug-ins to add views to the workbench. l Plug-ins that contribute a view must »register the view in their plugin.xml file and »provide configuration information about the view, such as –its implementation class, –the category (or group) of views to which it belongs, –the name and icon that should be used to describe the view in menus and labels. l The interface for views is defined in IViewPart, »but plug-ins can choose to extend the ViewPart class.

10 Example: l A declaration of the extension in the plugin.xml. <view id="org.eclipse.ui.examples.readmetool.views.Se ctionsView" name= "Readme Sections " icon="icons/view16/sections.gif" category="org.eclipse.ui.examples.readmetool" class="org.eclipse.ui.examples.readmetool.Read meSectionsView">

11 Category l we declare what extension point our plug-in is contributing using the extension element. l The org.eclipse.ui.views extension has several different configuration parameters. »We first declare a category for our view extension. »Categories can be used to group related views together in the workbench Show View dialog. »We define our own category, “readme" so that it will display in its own group. »We declare a unique id for our view and specify the name of the class that provides the implementation of the view. We also specify a name for the view, “Readme Sections" which will be shown in the Show View dialog and in our view's title bar.

12 Outline View for CUPSupport <view id=“nccu.cs.cupSupport.grammar.OutlineView" name= “Grammar Outline " icon="icons/cup.gif" category=“nccu.cs.cupSupport.cupViews" class=“nccu.cs.cupSupport.view.GRammarOutlin eView">

13 Types Workbench menu contributions l View Actions l Editor Actions l Popup Menus l Action Sets l Action Set Part Associations

14 org.eclipse.ui.viewActions l for plug-ins to contribute behavior to views that already exist in the workbench l This extension point allows plug-ins to contribute menu items, submenus and tool bar entries to an existing view's local pull-down menu and local tool bar.

15 You may have noticed an item in the navigator's local tool bar that becomes enabled whenever a readme file is selected. This item also appears in the navigator's local pull-down menu. These actions appear because the readme tool plug-in contributes them using the viewActions extension.

16

17 plugin.xml <viewContribution id="org.eclipse.ui.examples.readmetool.vc1" targetID="org.eclipse.ui.views.ResourceNavigator"> <action id="org.eclipse.ui.examples.readmetool.va1" label="%PopupMenu.ResourceNav.label" menubarPath="additions" toolbarPath="additions" icon="icons/obj16/editor.gif" tooltip="%PopupMenu.ResourceNav.tooltip" helpContextId="org.eclipse.ui.examples.readmetool.view_action _context" class="org.eclipse.ui.examples.readmetool.ViewActionDelegate" enablesFor="1"> <selection class="org.eclipse.core.resources.IFile“ name="*.readme"/>

18 l : unique id. l : the view to which we are adding the action. l l l The information in the plugin.xml is all that's needed to add items to menus and tool bars since plug-in code will only run when the action is actually selected from the menu or toolbar. To provide the action behavior, the implementation class specified in the plugin.xml must implement the IViewActionDelegate interface.

19 Types of workbench menu contributions 1. View Action: l extension point name: »org.eclipse.ui.viewActions l location of actions: »Actions appear in a specific view's local toolbar and local pulldown menu. l details: »Contribute an action class that implements IViewActionDelegate. Specify »the id of the contribution and »the id of the target view that should show the action. »The label and image dictate the appearance of the action in the UI. »The path specifies the location relative to the view's menu and toolbar items.

20 Editor Action l extension point : org.eclipse.ui.editorActions l location of action: »Actions are associated with an editor and appear in the workbench menu and/or tool bar. l Details: »Contribute an action class that implements IEditorActionDelegate. Specify »the id of the contribution and »the id of the target editor that causes the action to be shown. »The label and image specify the appearance of the action in the UI. »Separate menu and toolbar paths specify the existence and location of the contribution in the workbench menu and toolbar.

21 Popup Menus l extensin point name: org.eclipse.ui.popupMenus l location od actions: »Actions appear in the popup menu of an editor or view. »Actions associated with an object type show up in all popups of views and editors that show the object type. »Actions associated with a specific popup menu appear only in that popup menu.

22 l Details: »Object contributions specify » 1. the type of object for which the action should appear in a popup menu. »The action will be shown in all view and editor popups that contain the object type. »Provide an action class that implements IObjectActionDelegate. »Viewer contributions specify » 1. the id of the target popup menu in which the menu item should appear. »Provide an action class that implements IEditorActionDelegate or IViewActionDelegate.

23 Action Sets l extensin point : org.eclipse.ui.actionSets l location of actions: »Actions appear in the workbench main menus and toolbar. »Actions are grouped into action sets. »All actions in an action set will show up in the workbench menus and toolbars according to the user's selection of action sets and the current perspective shown in the workbench. »May be influenced by actionSetPartAssociations (below).

24 Action set part Association l extension point: actionSetPartAssociations l location: »Actions sets are shown only when the specified views or editors are active. »This is ignored if the user has customized the current perspective. l Details: »Specify an action set by id and followed by one or more parts (by id) that must be active in the current perspective in order to show the action set.

25 Details l Contribute an action class that implements IWorkbenchWindowActionDelegate or IWorkbenchWindowPulldownDelegate. l Specify the name and id of the action set. l Enumerate all of the actions that are defined for that action set. »For each action, separate menu and toolbar paths specify the existence and location of the contribution in the workbench menu and toolbar.