1

Eclipse PlatformPlug-in developper

Guide

PDG HowTos

2

Plugging into the workbench The workbench is the cockpit for navigating all of

the function provided by plug-ins. 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

we use the term workbench for referring to the workbench window (IWorkbenchWindow).

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. 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.

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 Inside the workbench window, you'll find one

page (IWorkbenchPage) that in turn contains parts.

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 A view is a workbench part that can navigate a hierarchy

of information or display properties for an object.  Only one instance of any given view is open in a

workbench page.  When the user makes selections or other changes in a

view, those changes are immediately reflected in the workbench.

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 The extension point org.eclipse.ui.views allows

plug-ins to add views to the workbench. 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. The interface for views is defined in IViewPart,

» but plug-ins can choose to extend the ViewPart class .

10

Example: A declaration of the extension in the plugin.xml.<extension point="org.eclipse.ui.views"> <category

id="org.eclipse.ui.examples.readmetool" name=“&readme"> </category>

<view id="org.eclipse.ui.examples.readmetool.views.SectionsView"

name="Readme Sections" icon="icons/view16/sections.gif" category="org.eclipse.ui.examples.readmetool" class="org.eclipse.ui.examples.readmetool.ReadmeSectionsView"></view>

</extension>

11

Category we declare what extension point our plug-in is contributing

using the extension element. 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<extension point="org.eclipse.ui.views"> <category id=“nccu.cs.cupSupport.cupViews"

name=“Cup-related Views?"> </category> <view

id=“nccu.cs.cupSupport.grammar.OutlineView"

name=“Grammar Outline" icon="icons/cup.gif" category=“nccu.cs.cupSupport.cupViews" class=“nccu.cs.cupSupport.view.GRammarOutlineView"></view>

</extension>

13

Types Workbench menu contributions

View Actions Editor Actions Popup Menus Action Sets Action Set Part Associations

14

org.eclipse.ui.viewActions for plug-ins to contribute behavior to views that

already exist in the workbench 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<extension point = "org.eclipse.ui.viewActions"> <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"/> </action> </viewContribution> </extension>

18

viewContribution/@id : unique id. viewContribution/@targetID : the view to which

we are adding the action. action/@id, action/@label, action/@icon, action/@tooltip, 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: extension point name:

» org.eclipse.ui.viewActions location of actions:

» Actions appear in a specific view's local toolbar and local pulldown menu.

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 extension point : org.eclipse.ui.editorActions location of action:

» Actions are associated with an editor and appear in the workbench menu and/or tool bar.

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 extensin point name:

org.eclipse.ui.popupMenus 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

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 extensin point : org.eclipse.ui.actionSets 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 extension point: actionSetPartAssociations 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.

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 Contribute an action class that implements

IWorkbenchWindowActionDelegate or IWorkbenchWindowPulldownDelegate.

Specify the name and id of the action set. 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.