<!doctype html public "-//w3c//dtd html 4.0//en"> | |
<html> | |
<head> | |
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
<title>Desktop - Readme Tool Example</title> | |
</head> | |
<body> | |
<h2> | |
<b>Example - Readme Tool</b></h2> | |
<h3> | |
Introduction</h3> | |
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. | |
<h3> | |
Running the example</h3> | |
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 | |
Perspectives > Show View > Other and expanding the Readme section. The | |
view action can be seen by clicking on the readme icon on the Navigator | |
View. | |
<h4> | |
Creating a new readme file</h4> | |
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. | |
<h4> | |
Example creation wizards</h4> | |
From the File menu, select New and from the sub menu select Other... | |
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. | |
<h4> | |
Readme view extension action</h4> | |
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. | |
<h4> | |
Popup menus</h4> | |
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. | |
<h4> | |
Preference page</h4> | |
From the Window menu, select Preferences. Click on the page called | |
Readme Example. This shows an example of a preference page. | |
<h4> | |
Property page</h4> | |
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. | |
<h4> | |
Readme file editor</h4> | |
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. | |
<h4> | |
Readme Editor Actions</h4> | |
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. | |
<p>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. | |
<h4> | |
Readme sections view</h4> | |
To see this Readme Sections view, from the Perspective 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. | |
<p>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. | |
<p>Example text: | |
<p>99.1 This is my first section | |
<br>This is some text in my first section. | |
<p>99.1.1 This is a sub section | |
<br>This is some text in my sub-section. | |
<h4>Drag and Drop</h4> | |
<p>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. | |
<h4> | |
Help contribution</h4> | |
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). | |
<br> | |
<h3> | |
Details</h3> | |
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. | |
<p>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. | |
<p>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. | |
<p>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 Workbench->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. | |
<p>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->Other.... | |
<p>Several action stubs are added to this example. The action set declares | |
a menu labeled Readme File Editor<b> </b>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.<p>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. | |
<p><a href="hglegal.htm"><img SRC="ngibmcpy.gif" ALT="Copyright IBM Corp. 2000, 2001. All Rights Reserved." BORDER=0 height=12 width=195></a> | |
</body> | |
</html> |