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.