Example - Readme Tool
Introduction
The Readme editor shows how to define your own extension points for use
by other plugins. It also shows how to create extensions for resource popup
menu entries, new resource wizards, file editors on an extension (.readme),
a custom view and property pages.
Running the example
To start using this example create a file with the .readme extension using
the file creation wizard or create one using the example creation wizard.
The additional view provided by this example can be seen by selecting
Window > Show View > Other and expanding the Readme section. The
view action can be seen by clicking on the readme icon on the Navigator
View.
Creating a new readme file
Create a new file with file extension .readme. From the File menu,
select New and then select Other... from the sub menu. Click on Simple
in the wizard, then select File in the list on the left. Click on
Next to supply the file name (make sure the extension is .readme) and the
folder in which the file should be contained.
Example creation wizards
From the File menu, select New and from the sub menu select Example...
Now select Example Creation Wizards. Select Readme File. Click Next. Select
the folder in which you want the file to be created. Type the name of the
file with a .readme extension. Click Finish.
Readme view extension action
In the Navigator View, select a file with extension .readme. If there isn't
one create a file with that extension. On the local toolbar of the Navigator
View, you will see a button whose hover help says Run Readme View Extension.
Click on this button. A dialog will popup saying View Action executed.
Popup menus
In the Navigator View, select a file with extension .readme. If there
isn't one create a file with that extension. Select the file to bring
up the popup menu. Notice there is a menu item that says Show Readme
Action in the popup menu. Choose this menu item to open a dialog
that says Popup Menu Action Executed.
Preference page
From the Window menu, select Preferences. Click on the page called
Readme Example. This shows an example of a preference page.
Property page
In the Navigator View, select a file with extension .readme. If there
isn't one create a file with that extension. Select the file to bring
up the popup menu, then select the Properties menu item. Click on
the page called Readme Tool to see an example of a property page.
Readme file editor
The Readme File Editor is the default editor for files of type *.readme.
Create a file with extension .readme and open the file by double clicking
on it, or by bringing up the popup menu, selecting Open With, then
selecting Readme File Editor from the sub menu. Notice the editor
has an icon with a pencil. This is the editor that the readme tool
uses by default for files of type *.readme.
Readme Editor Actions
This demonstrates an example of actions that are applicable only to a particular
editor. When a readme file editor has focus, notice 4 additional
tool bar buttons - Run Readme Editor Extension, Readme Editor Action 1,
Readme Editor Action 2, Readme Editor Action 3.
A pull down menu named Readme appears when a readme file editor has
focus. It contains the actions previously described: Readme Editor
Action 1, Readme Editor Action 2, Readme Editor Action 3.
Readme sections view
To see this Readme Sections view, from the Window menu select Show
View, then select Other... from the sub menu. Expand the Readme item
and then select Readme Sections. This will show a list of the sections
in the current *.readme file when a .readme file is selected in the Navigator
View. You can also see the structure of a *.readme file in the Outline
view.
A file with extension .readme can be broken down into sections when
each section begins with a number. For example, if the following
text were entered into the readme file editor, the readme tool would detect
2 sections. To see how sections are detected in the readme tool,
type some text in the readme file editor, save the file by either typing
CTRL-S or selecting File->Save. Open the Readme Sections view and
select the .readme file in the Navigator View.
Example text:
99.1 This is my first section
This is some text in my first section.
99.1.1 This is a sub section
This is some text in my sub-section.
Drag and Drop
The Drag and Drop functionality can be seen by selecting a section in the
Outline View and dragging the selection over top of a text file. The contents of
the selection will be appended to the file.
Help contribution
The readme tool example also demonstrates how to use and implement context
help on all of the extensions it supplies - a view, various actions and
a wizard page. To get context help on an action, hover over the menu
item, but do no select it, then hit the F1 key. You can also get
context sensitive (F1) help on the Readme Sections view and the Example
Creation Wizards page (in the New wizard).
Details
The Readme Tool example declares one extension point and supplies a number
of extensions. The extensions supplied are quite comprehensive in
understanding how the Workbench functions, as it utilizes a number of the
more interesting extension points declared by the workbench. Supplied
extensions included in this example are views and view actions, preference
pages, property pages, wizards, editors and editor actions, popup menus,
action sets, help contributions, help contexts, and drop actions.
This example also supplies an extension point declared in the plug-in..
The class IReadmeFileParser is required for any plug-in that uses the org.eclipse.ui.examples.readmetool.sectionParser
extension that this example defines. The class DefaultSectionParser is
an example implementation of IReadmeFileParser.
The class ReadmeEditor implements IEditorPart and is defined as an editor
on files with the extension .readme in the plugin.xml using the org.eclipse.ui.editors
extension point. The class ReadmeSectionsView implements IViewPart and
is defined as a view using the org.eclipse.ui.views extension point. This
extension point also defines a category for the view for use in view selection.
Two types of preference settings are defined in this example, workbench
preferences and resource properties. The workbench preference is defined
in class ReadmePreferencePage which implements IWorkbenchPreferencePage
so that it will be added to the Window->Preferences dialog. The class
is defined in the extension point org.eclipse.ui.preferencePages in the
plugin.xml. The two resource properties pages are ReadmeFilePropertyPage
and ReadmeFilePropertyPage2 both of which implement IWorkbenchPropertyPage.
They are both defined to be invoked on the IFile type by the objectClass
tag in the plugin.xml in the org.eclipse.ui.propertyPages extension point.
The class ReadmeCreationWizard implements INewWizard and is defined
in the org.eclipse.ui.newWizards extension point in the plugin.xml. This
extension point also defines the category that the wizard that is shown
when the user selects File->New->Example....
Several action stubs are added to this example. The action set declares
a menu labeled Readme File Editor to be included in the workbench
window menu bar using the extension point org.eclipse.ui.actionSets. It
also defines an action for the workbench toolbar and menu bar using the
tags toolbarPath and menubarPath. It uses the class WindowActionDelegate
which implements IWorkbenchWindowActionDelegate to implement the action.
The action for the popup menu is defined as an objectContribution by the
class PopupMenuActionDelegate in the extension point org.eclipse.ui.popupMenus.
PopupMenuActionDelegate implements IObjectActionDelegate and uses the IWorkbenchPart
provided to open a message dialog. The view action ViewActionDelegate is
defined in the extension point org.eclipse.ui.viewActions and implements
IViewActionDelegate. The View it appears in is defined by the tag targetID
which in this example is org.eclipse.ui.views.ResourceNavigator. The editor
action is defined by the class EditorActionDelegate which implements IEditorActionDelegate
and is added using the org.eclipse.ui.editorActions extension point. The
editor that it is applied to is defined by the tag targetID which in this
example is defined on org.eclipse.ui.examples.readmetool.ReadmeEditor.
The
class ReadmeDropActionDelegate implements IDropDelegate. IDropDelegates are
informed every time there is a drop action performed in the workbench . The
extension point for this action is org.eclipse.ui.dropActions.
