Eclipse Plug-ins and RCP
Training CourseStandard Extension Points
and their APIs
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions1
1. Views and Perspectives
2. Editorsa) 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 Pointa) Schema definition
b) Parsing extensions content
c) Executable extensions
Agenda
2October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions
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 Solutions3
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.
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 Solutions4
October 2013
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 Solutions5
October 2013
Purpose Group Eclipse views, commands , shortcuts for a particular task.
Package org.eclipse.ui
Extension Point org.eclipse.ui.perspectivesorg.eclipse.ui.perspectiveExtensions
Interface(s) org.eclipse.ui.IPerspectiveFactory
Super Class(es)
Perspectives
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions6
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
Purpose Create and modify resources.Follow the paradigm Open-Modify-Save.
Package org.eclipse.uiorg.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 Solutions7
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
sd Editor Lifecycle
User
(from Class Model)
part::EditorPart Editor ModelUI Resource ChangeListener
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 Solutions8
October 2013
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 Solutions9
October 2013
Forms (2/2)
Copyright © 2013 Luca D’Onofrio – RCP Solutions10
October 2013
class part
EditorPart
MultiPageEditor
ViewPartEventManager
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 Solutions11
October 2013
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 Solutions12
October 2013
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 Solutions13
October 2013
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 Solutions14
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.propertyContributororg.eclipse.ui.views.properties.tabbed.propertyTabsorg.eclipse.ui.views.properties.tabbed.propertySections
Super Class(es) org.eclipse.ui.views.properties.tabbed.AbstractPropertySection
Properties View
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions15
Selection enablement through extension point enablement statement
Create Control Set and check the input Refresh section content
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.uiorg.eclipse.core.runtime
Extension Point org.eclipse.ui.preferencePagesorg.eclipse.core.runtime.preferences
Interface(s) org.eclipse.ui.IWorkbenchPreferencePage
Super Class(es) org.eclipse.jface.preference.PreferencePageorg.eclipse.jface.preference.FieldEditorPreferencePageorg.eclipse.core.runtime.preferences.AbstractPreferenceInitializer
Plugin Preferences (1/2)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions16
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
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 Solutions17
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 Solutions18
Persistent Properties VS Session Properties Since PropertyPage inherits from PreferencePage, with little
effort the Property Page can be reused as a Preference Page.
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 Solutions19
Purpose Declaring and implementing functions that manifest as menu items and toolbar buttons.
Package org.eclipse.ui
Extension Point org.eclipse.ui.commandsorg.eclipse.ui.handlersorg.eclipse.ui.bindings
Super Class(es) org.eclipse.core.commands.AbstractHandler
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 Solutions20
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 Solutions21
Purpose UI representation in a menu or in a toolbar
Package org.eclipse.ui
Extension Point org.eclipse.ui.menus
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 Solutions22
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 Solutions23
Purpose Help you integrate document models into a navigator experience.
Package org.eclipse.ui.navigator
Extension Point org.eclipse.ui.navigator.navigatorContentorg.eclipse.ui.navigator.linkHelperorg.eclipse.ui.navigator.viewer
Interface(s) org.eclipse.ui.navigator.ILinkHelper
Common Navigator Framework (1/2)
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions24
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
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 Solutions25
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 Solutions26
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.INewWizardorg.eclipse.jface.wizard.IWizardPage
Super Class(es) org.eclipse.jface.wizard.Wizardorg.eclipse.jface.wizard.WizardPage
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 Solutions27
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
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 Solutions28
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
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 Solutions29
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
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 Solutions30
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
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 Solutions31
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.cheatSheetContentorg.eclipse.ui.cheatsheets.cheatSheetItemExtension
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 Solutions32
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.introorg.eclipse.ui.intro.configorg.eclipse.ui.intro.configExtension
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 Solutions33
Extension Point Schema Definition
Copyright © 2013 Luca D’Onofrio – RCP Solutions34
Schema documentation General Element / attribute
specific Schema inclusions Elements XML
structure Elements Attributes
Boolean String Java Resource Identifier October 2013
act Load extensions
Get Platform Extension Registry
Retriev e 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 Solutions35
October 2013
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 Solutions36
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 Solutions37
www.eclipse.orghelp.eclipse.orgwiki.eclipse.orgEclipse SDK update site
http://download.eclipse.org/eclipse/updates/4.3
References
October 2013Copyright © 2013 Luca D’Onofrio – RCP Solutions38