| <!doctype html public "-//w3c//dtd html 4.0//en"> |
| <html> |
| <head> |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <title>Workbench - 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 |
| 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. |
| <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 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. |
| <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 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. |
| <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 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. |
| <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->Example.... |
| <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. |
| |
| </body> |
| </html> |