Eclipse Training - Standard Extension Points and APIs Example code available at: https://code.google.com/p/eclipse-training-course/

1. Eclipse Plug-ins
and RCP
Training Course
Standard Extension Points and
their APIs
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
1

2. 1. Views and Perspectives
2. Editors
a) Forms
b) Tracking resource changes
3. Properties View
4. Plugin Preferences and Resource Properties
5. Commands, key binding, menu and toolbar
6. Common Navigator Framework
7. Wizards, Builders, Markers, Project Nature
8. Help, Cheat sheets, Welcome page
9. Define a new Extension Point
a) Schema definition
b) Parsing extensions content
c) Executable extensions
Agenda
2
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions

3. Purpose Provide information and functionalities to the user.
Package org.eclipse.ui
Extension Point org.eclipse.ui.views
Interface(s) org.eclipse.ui.IViewPart
Super Class(es) org.eclipse.ui.part.ViewPart
Views (1/3)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
3
∗ Views are contained in a View Site, which is contained in a Workbench
Page
∗ The Workbench page keep an instance of IViewReference (Lazy
Initialization: views can be enumerated and referenced without actually
loading the plug-in that defines the view.
∗ Views share a common behavior with editors, but:
∗ Any action performed on a view should immediately effect the state of the
workbench and the underlying resources
∗ Editors follow the open-modify-save paradigm.

4. ∗ JFace Actions
∗ Declare and implement functions that will be displayed as menu items
of toolbar buttons.
∗ The controls for a command are built by some container, which
furnished the context where these controls appear and configures
them with data from properties declared by the action.
∗ When the end user triggers the command via its control, the action's
run method is invoked to do the real work.
∗ Actions support a predefined set of properties (and possibly others as
well). Clients of an action may register property change listeners so
that they get notified whenever the value of a property changes.
∗ Clients should subclass the abstract base class Action to define
concrete actions rather than implementing IAction from scratch.
Views (2/3)
Copyright © 2013 Luca D’Onofrio – RCP Solutions
4
October 2013

5. ∗ Main Concepts
∗ Category: used to group views
∗ Controls: views typically can contain any number of controls (SWT +
JFace)
∗ Memento: save the local state of the view in order to restore it across
multiple sessions.
∗ Selections Listeners and Providers: update state according to part
selection.
∗ Adaptable: the view can participate in various workbench behaviors
implementing the getAdapter(Class) method of IAdaptable interface. This
allow an object to convert one type of object that it may no understand
to another type of object that it can interrogate or manipulate.
∗ Context Help, Menu and Toolbar
Views (3/3)
Copyright © 2013 Luca D’Onofrio – RCP Solutions
5
October 2013

6. Purpose Group Eclipse views, commands , shortcuts for a
particular task.
Package org.eclipse.ui
Extension Point org.eclipse.ui.perspectives
org.eclipse.ui.perspectiveExtensions
Interface(s) org.eclipse.ui.IPerspectiveFactory
Super Class(es)
Perspectives
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
6
∗ Create a new Perspective
∗ Extend an existing perspective (or all using “*” as targetID)
∗ Layout:
∗ Define the layout using perspectiveExtensions
∗ Create a layout programmatically using IPerspectiveFactory and
IPageLayout

7. Purpose Create and modify resources.
Follow the paradigm Open-Modify-Save.
Package org.eclipse.ui
org.eclipse.ui.forms
Extension Point org.eclipse.ui.editors
(org.eclipse.core.contenttype.contentTypes)
Interface(s) org.eclipse.ui.IEditorPart
Super Class(es) org.eclipse.ui.EditorPart
Editors (1/2)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
7
∗ Editor elements:
∗ Contributor Class
∗ Content Type Binding
∗ Editor Commands (i.e. activating command handler on active editor)
∗ Main Editor types:
∗ MultiPage Editor, FormEditor, TextEditor, XMLEditor

8. sd Editor Lifecycle
User
(from Class Model)
part::EditorPart Editor ModelUI Resource Change
Listener
Resource
Open Resource()
Open Editor on Resource()
init(IEditorSite, IEditorInput)
Build Model()
createPartControl(Composite)
Resource changed from outside()
Notify Listener()
Update Model()
Update Editor Content()
Modify Editor Content()
Update Model()
Update Model()
firePropertyChange(PROP_DIRTY)
Save()
doSave(IProgressMonitor)
Store changes permanently()
firePropertyChange(PROP_DIRTY)
Editors (2/2)
Copyright © 2013 Luca D’Onofrio – RCP Solutions
8
October 2013

9. ∗ Eclipse Forms is an optional Rich Client plug-in based on SWT and JFace that provides
the support for creating portable web-style user interfaces across all Eclipse UI
categories.
∗ Eclipse Forms support uses the existing widget set to achieve a richer user experience.
∗ Eclipse Forms make these rich user interfaces possible with the following elements:
∗ A concept of a 'form' that is suitable for inclusion in content areas such as views
and editors
∗ A toolkit to manage colors, hyperlink groups and other aspects of a form, and
serve as a factory for many SWT controls
∗ A new layout manager that lays out controls in a manner similar to an HTML table
layout algorithm
∗ A set of custom controls designed to fit in the form (hyperlink, image hyperlink,
scrollable composite, section)
∗ A multi-page editor where most or all of the pages are forms (e.g. PDE manifest
editors, Master/Detail)
Forms (1/2)
Copyright © 2013 Luca D’Onofrio – RCP Solutions
9
October 2013

10. Forms (2/2)
Copyright © 2013 Luca D’Onofrio – RCP Solutions
10
October 2013

11. class part
EditorPart
MultiPageEditor
ViewPart
EventManager
IExecutableExtension
WorkbenchPart
IAdaptable
«interface»
ui::IEditorInput
ISaveablePart
«interface»
ui::IEditorPart
IPersistable
«interface»
ui::IViewPart
IAdaptable
«interface»
ui::
IWorkbenchPart
editor::FormEditoreditor::FormEditor::
FormPage
forms::
MasterDetailsBlock
forms::DetailsPart
{leaf}
IPartSelectionListener
«interface»
forms::IDetailsPage
«interface»
forms::IFormPart
«interface»
forms::
IManagedForm forms::
ManagedForm
IPageChangeProvider
MultiPageEditorPart
«interface»
editor::IFormPage
-masterPart
-managedForm
#detailsPart
-editorInput
-editor
Workbench Parts
Architecture
Copyright © 2013 Luca D’Onofrio – RCP Solutions
11
October 2013

12. ∗ Eclipse generate resources changes events
tracking the status of a file system resource
∗ Interested objects can subscribe (listen) to the
events notification, implementing
IResourceChangeListener
Tracking resource changes
Copyright © 2013 Luca D’Onofrio – RCP Solutions
12
October 2013

13. ∗ Events:
∗ PRE_BUILD: before-the-fact report of builder activity
∗ PRE_CLOSE: before-the-fact report of the impending closure of a
single project
∗ PRE_DELETE: before-the-fact report of the impending deletion of a
single project
∗ PRE_REFRESH: before-the-fact report of refreshing of a project.
∗ POST_BUILD: after-the-fact report of builder activity
∗ POST_CHANGE: after-the-fact report of creations, deletions, and
modifications to one or more resources expressed as a hierarchical
resource delta
Tracking resource changes
Events
Copyright © 2013 Luca D’Onofrio – RCP Solutions
13
October 2013

14. ∗ Each individual change is encoded as an instance of a
resource delta that is represented by the
IResourceDelta interface.
∗ ADDDED, CHANGED, COPIED_FROM, MOVED_FROM OPEN,
REMOVED, REPLACED, SYNC, TYPE, …
Tracking resource changes
Deltas
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
14

15. Purpose The properties view displays property names and values
for a selected item such as a resource. It can also arrange
information in a more user-friendly way using Tab
Sections.
Package org.eclipse.ui
Extension Point org.eclipse.ui.views.properties.tabbed.propertyContributor
org.eclipse.ui.views.properties.tabbed.propertyTabs
org.eclipse.ui.views.properties.tabbed.propertySections
Super Class(es) org.eclipse.ui.views.properties.tabbed.AbstractPropertySe
ction
Properties View
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
15
∗ Selection enablement through extension point enablement statement
∗ Create Control
∗ Set and check the input
∗ Refresh section content

16. Purpose A preference is data that is persisted between workspace
sessions to allow the user to keep the state of a plug-in
consistent between Eclipse sessions.
Package org.eclipse.ui
org.eclipse.core.runtime
Extension Point org.eclipse.ui.preferencePages
org.eclipse.core.runtime.preferences
Interface(s) org.eclipse.ui.IWorkbenchPreferencePage
Super Class(es) org.eclipse.jface.preference.PreferencePage
org.eclipse.jface.preference.FieldEditorPreferencePage
org.eclipse.core.runtime.preferences.AbstractPreferenceIn
itializer
Plugin Preferences (1/2)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
16
∗ Initialize preference store
∗ Nest preference pages, arrange them in tabs
∗ Access field values by its key using the PreferenceStore, according to its own type
∗ Listening for preference changes by adding IPropertyChangeListener

17. ∗ A field editor is designed to load, display, edit and save a particular preference
setting. Available field editors are:
∗ BooleanFieldEditor
∗ ColorFieldEditor
∗ DirectoryFieldEditor
∗ FileFieldEditor
∗ FontFieldEditor
∗ IntegerFieldEditor
∗ RadioGroupFieldEditor
∗ ScaleFieldEditor
∗ StringFieldEditor
∗ A validator can be associated with a field editor, also displaying info messages
∗ You can create your own field editor
Plugin Preferences (2/2)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
17

18. Purpose A resource property is data that is persisted between
workspace sessions to allow the user to keep the state of
a resource consistent between Eclipse sessions.
Package org.eclipse.ui
Extension Point org.eclipse.ui.propertyPages
Interface(s) org.eclipse.ui.IWorkbenchPropertyPage
Super Class(es) org.eclipse.ui.dialogs.PropertyPage
Resource Properties
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
18
∗ Persistent Properties VS Session Properties
∗ Since PropertyPage inherits from PreferencePage, with little effort the
Property Page can be reused as a Preference Page.

19. ∗ Commands separate implementation from presentation, by providing an extension point for
specifying the command and other extension points to specify where it should appear in the UI.
∗ Main commands elements:
∗ Category: group one or more commands
∗ Handler: realize the command behavior
∗ Key binding: associate the command with a key sequence (data binding)
∗ Menu contribution: UI representation in a menu
∗ Toolbar contribution: UI representation in a toolbar
∗ A command can also be executed programmatically using the ICommandService interface
Commands
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
19
Purpose Declaring and implementing functions that manifest as
menu items and toolbar buttons.
Package org.eclipse.ui
Extension Point org.eclipse.ui.commands
org.eclipse.ui.handlers
org.eclipse.ui.bindings
Super Class(es) org.eclipse.core.commands.AbstractHandler

20. ∗ The org.eclipse.ui.bindings extension point is used to declare
bindings and schemes.
∗ Schemes are sets of one or more bindings.
∗ A binding is a mapping between a certain group of conditions, some
user input and a triggered command.
∗ All bindings require a trigger of some kind, a context in which they
are active and scheme in which they exist. (e.g.
“org.eclipse.ui.contexts.window”, binding will apply in any Eclipse
main window.
∗ Other examples of data binding:
∗ Editor contentTypeBinding
∗ Viewer viewerContentBinding
Commands and data
binding
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
20

21. ∗ Define where and when the command should appear in the user interface
∗ Where: locationURI identifies the location in the user interface where
commands associated with this menu contribution will appear
∗ When: visibleWhen expression controls when the particular menu or
toolbar items are visible in the user interface
TIP: this can be used instead of Editor Contribution (see Editors)
Menu and Toolbar
Contribution (1/3)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
21
Purpose UI representation in a menu or in a toolbar
Package org.eclipse.ui
Extension Point org.eclipse.ui.menus

22. ∗ Common location identifiers:
∗ org.eclipse.ui.main.menu: identifies the Eclipse main
menu
∗ org.eclipse.ui.main.toolbar: identifies the Eclipse
main toolbar
∗ org.eclipse.ui.popup.any: identifies any context
menu
Menu and Toolbar
Contribution (2/3)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
22

23. ∗ visibleWhen elements:
∗ Logical operators: and, or, not
∗ Selection based operators: with, count, iterate
∗ With variables:
∗ activeContexts
∗ activeEditorId
∗ activePartId
∗ selection
∗ Object testing: adapt, equals, instanceof, systemTest, test
∗ propertyTester: extension used to evaluate the state of a particular object
(org.eclipse.core.expressions.PropertyTester)
∗ e.g. IResource
∗ org.eclipse.core.resources.name
∗ org.eclipse.core.resources.path
∗ org.eclipse.core.resources.extension
Menu and Toolbar
Contribution (3/3)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
23

24. Purpose Help you integrate document models into a navigator
experience.
Package org.eclipse.ui.navigator
Extension Point org.eclipse.ui.navigator.navigatorContent
org.eclipse.ui.navigator.linkHelper
org.eclipse.ui.navigator.viewer
Interface(s) org.eclipse.ui.navigator.ILinkHelper
Common Navigator
Framework (1/2)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
24
∗ The Common Navigator Framework (CNF) is a facility provided by the Eclipse
Platform which allows the usage of multiple Label- and ContentProvider on the
same view.
∗ The providers are activated and used dynamically and can be configured
declarative or programmatically. The advantage of CNF approach is the ability to
combine elements in one view which have different origins
∗ Content can be dynamically linked with an editor

25. ∗ Behavior:
∗ If an element is selected in the viewer, the CNF consults
triggerPoints of all Navigation Content Extensions (NCEs) provided
and tries to match the element to the trigger point expression.
∗ If the expression matches, the NCE is activated by the platform and
the corresponding contentProvider is responsible for delivering
content.
∗ If the element is activated by other means than in the viewer (e.g.
in the Editor), the platform consults possibleChildren list and tries
to match the corresponding expression
Common Navigator
Framework (2/2)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
25

26. ∗ Wizards can contain multi-page content.
∗ The IWizardPage interface provides method to control the life-cycle of the
page content (input validate and messages, wizard steps enablement, …).
∗ User can launch a wizards through the UI or programmatically.
Wizards
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
26
Purpose Wizards are a specialized dialogs (modal) that collect a set
of information in order to perform a specialized task (e.g.
create a resource, …)
Package org.eclipse.ui
Extension Point org.eclipse.ui.newWizards
Interface(s) org.eclipse.ui.INewWizard
org.eclipse.jface.wizard.IWizardPage
Super Class(es) org.eclipse.jface.wizard.Wizard
org.eclipse.jface.wizard.WizardPage

27. ∗ Builder are associated to a project in the workspace
∗ Builder are notified (see Tracking resource changes) when a
resource changes.
∗ A builder must be executed incrementally (i.e. it must rebuild
only those resources that have changed).
Project Builders
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
27
Purpose Builders are responsible for update a project internal build
state and of all its derived resources.
Package org.eclipse.core.resources
Extension Point org.eclipse.core.resources.builders
Super Class(es) org.eclipse.core.resources.IncrementalProjectBuilder

28. ∗ You can add or delete a marker through IResource.createMarker
∗ You can retrieve resource markers through IResource.findMarkers
∗ Markers are showed in a Eclipse view, corresponding to the marker type
∗ Markers Types: BOOKMARK, MARKER, PROBLEM, TASK, TEXT
∗ Before adding markers you must remove old markers
∗ Markers Attributes:
∗ LINE_NUMBER, CHAR_START, CHAR_END
∗ LOCATION (human readable string)
∗ PRIORITY
∗ SEVERITY (Error, Warning, Info)
Markers
Copyright © 2013 Luca D’Onofrio – RCP Solutions
28
Purpose Markers are used to annotate specific location within a
resource.
Package org.eclipse.core.resources
Extension Point org.eclipse.core.resources.markers
October 2013

29. ∗ Natures can have the behavior to configure/deconfigure a
project using the IProjectNature interface in the <runtime>
extension element.
∗ A Nature may depend on other natures.
∗ You can associate a Nature to a project programmatically
(e.g. on project creation) or using a command
∗ Natures can have their own image/decorator
Project Nature
Copyright © 2013 Luca D’Onofrio – RCP Solutions
29
Purpose A project nature is used to associate a project with
functionalities such as builders.
Package org.eclipse.core.resources
Extension Point org.eclipse.core.resources.natures
Interface(s) org.eclipse.core.resources.IProjectNature
October 2013

30. ∗ Context Sensitive Help (F1): support for context sensitive help for views, widgets, actions, …
∗ Each context sensitive help contains a unique id associated with to object providing the help
(<plugin-id>.<local-context-id>)
∗ A context.xml file contains the context topics and their links to specific html pages
∗ Eclipse Help window is a separate (non-modal) window
∗ Help extension refers one or more table of context xml files (toc): a label specifies te text
displayed in the topic list, while the topic attribute specifies the the documentation page.
∗ Top-down help composition
∗ Bottom-up help composition (anchor points)
TIP: use fragments in order to provide an elegant solution when building your application (see I18N)
TIP: Help toc or pages can be also displayed programmatically
Help System
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
30
Purpose Contribute to the Eclipse infrastructure that provides help
documentation into the environment.
Package org.eclipse.ui
Extension Point org.eclipse.help.toc org.eclipse.help.contexts

31. ∗ An XML file describes the content of a cheat sheet for each step:
∗ Item element specifies the title and body display text of the step
∗ Command element (optional), represents an executable
workbench command to automate the task required by the step
∗ Help element (optional) adds a help link that will open related help
in a separate window or browser when clicked
∗ With cheatSheetItemExtension extension point user can
customize some UI aspects of each step
Cheat Sheets
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
31
Purpose Used support the user, describing a series of steps
needed to complete a task.
Package org.eclipse.ui.cheatsheets
Extension Point org.eclipse.ui.cheatsheets.cheatSheetContent
org.eclipse.ui.cheatsheets.cheatSheetItemExtension

32. ∗ Different possible forms of welcome:
∗ simple static text
∗ elaborate extendable multi-page presentations
∗ Universal Welcome (configId="org.eclipse.ui.intro.universalConfig") which defines a common
page structure, allowing several products to share the welcome space.
∗ config is used to register an intro configuration. This configuration provides presentation
implementations and content for a given intro contribution.
∗ configExtension is used to extend an existing intro configuration by providing more content
∗ intro is used to register implementations of special workbench parts, called intro parts, that are
responsible for introducing a product to new users.
Welcome Page
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
32
Purpose The welcome page is the first page you see when you first
launch eclipse. Its purpose is to introduce you to the
product.
Package org.eclipse.ui
Extension Point org.eclipse.ui.intro
org.eclipse.ui.intro.config
org.eclipse.ui.intro.configExtension

33. ∗ Each plugin can define its own extension points
∗ Purposes:
∗ Define a more elegant and abstract architectural model of your application
∗ Provide hooks to third-party plugins to enhance your product
∗ Extension Point elements:
∗ Unique identifier
∗ Name
∗ Schema definition
Define a new
Extension Point
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
33

34. Extension Point Schema
Definition
Copyright © 2013 Luca D’Onofrio – RCP Solutions
34
∗ Schema documentation
∗ General
∗ Element / attribute
specific
∗ Schema inclusions
∗ Elements XML structure
∗ Elements Attributes
∗ Boolean
∗ String
∗ Java
∗ Resource
∗ Identifier
October 2013

35. act Load extensions
Get Platform Extension
Registry
Retrieve Extension Point
Get Extensions
Get Configuration
Elements and Attributes
The declaring plugin is
not activated yet.
Load an extension class
The plugin has been
activated
Start
End
Do some work
Close your RCP
The plugin has been
deactivated.
Parsing extensions content
(1/2)
Copyright © 2013 Luca D’Onofrio – RCP Solutions
35
October 2013

36. ∗ Retrieve the extensions matching your extension point unique identifier:
IExtensionRegistry registry = Platform.getExtensionRegistry();
IExtensionPoint point = registry.getExtensionPoint(ExtensionParser.EXTENSION_ID);
IExtension[] extensions = point.getExtensions();
∗ Create a proxy in order to retrieve all the extension information without
loading the plugin.
∗ A configuration element, with its attributes and children, directly reflects
the content and structure of the extension section within the declaring
plug-in's manifest (plugin.xml) file.
∗ This interface also provides a way to create executable extension objects.
Parsing extensions content
(2/2)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
36

37. Object executable = config.createExecutableExtension(<attribute>);
∗Creates and returns a new instance of the executable extension
identified by the named attribute of this configuration element.
∗The named attribute value must contain a fully qualified name of
a Java class. The class can either refer to a class implementing the
executable extension or to a factory capable of returning the
executable extension.
Executable extensions
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
37

38. ∗ www.eclipse.org
∗ help.eclipse.org
∗ wiki.eclipse.org
∗ Eclipse SDK update site
∗ http://download.eclipse.org/eclipse/updates/4.3
References
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
38