Eclipse Training - Standard Extension Points and APIs

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)


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)


October 2013

Purpose Group Eclipse views, commands , shortcuts for a particular task.


Extension Point org.eclipse.ui.perspectivesorg.eclipse.ui.perspectiveExtensions

Interface(s) org.eclipse.ui.IPerspectiveFactory

Super Class(es)

Perspectives


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)


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)


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)


October 2013

Forms (2/2)


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


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


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


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


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.


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


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)


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)


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.


Extension Point org.eclipse.ui.propertyPages

Interface(s) org.eclipse.ui.IWorkbenchPropertyPage

Super Class(es) org.eclipse.ui.dialogs.PropertyPage

Resource Properties


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


Purpose Declaring and implementing functions that manifest as menu items and toolbar buttons.


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


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)


Purpose UI representation in a menu or in a toolbar


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



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



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)


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)


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


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, …)


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


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


Purpose Markers are used to annotate specific location within a resource.


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


Purpose A project nature is used to associate a project with functionalities such as builders.


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


Purpose Contribute to the Eclipse infrastructure that provides help documentation into the environment.


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


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


Purpose The welcome page is the first page you see when you first launch eclipse. Its purpose is to introduce you to the product.


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


Extension Point Schema Definition


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)


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)


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


www.eclipse.orghelp.eclipse.orgwiki.eclipse.orgEclipse SDK update site

http://download.eclipse.org/eclipse/updates/4.3

References


Eclipse Training - Standard Extension Points and APIs

Technology