examples/org.eclipse.ui.examples.readmetool/doc-html/ui_readmetool_ex.html - platform/eclipse.platform.ui - Git at Google

 <!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&nbsp; 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.&nbsp; From the File menu,
 select New and then select Other... from the sub menu.&nbsp; Click on Simple
 in the wizard, then select File in the list on the left.&nbsp; 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...&nbsp;
 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.&nbsp;
 Click on this button.&nbsp; A dialog will popup saying View Action executed.
 <h4>
 Popup menus</h4>
 In the Navigator View, select a file with extension .readme.&nbsp; If there
 isn't one create a file with that extension.&nbsp; Select the file to bring
 up the popup menu.&nbsp; Notice there is a menu item that says Show Readme
 Action in the popup menu.&nbsp; Choose this menu item to open a dialog
 that says Popup Menu Action Executed.
 <h4>
 Preference page</h4>
 From the Window menu, select Preferences.&nbsp; Click on the page called
 Readme Example.&nbsp; This shows an example of a preference page.
 <h4>
 Property page</h4>
 In the Navigator View, select a file with extension .readme.&nbsp; If there
 isn't one create a file with that extension.&nbsp; Select the file to bring
 up the popup menu, then select the Properties menu item.&nbsp; 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.&nbsp;
 Create a file with extension .readme and open the file by double clicking
 on it, or by bringing up the popup menu,&nbsp; selecting Open With, then
 selecting Readme File Editor from the sub menu.&nbsp; Notice the editor
 has an icon with a pencil.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; Expand the Readme item
 and then select Readme Sections.&nbsp; This will show a list of the sections
 in the current *.readme file when a .readme file is selected in the Navigator
 View.&nbsp; 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.&nbsp; For example, if the following
 text were entered into the readme file editor, the readme tool would detect
 2 sections.&nbsp; 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&nbsp; 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.&nbsp; To get context help on an action, hover over the menu
 item, but do no select it, then hit the F1 key.&nbsp; You can also get
 context sensitive (F1) help on the Readme Sections view and the Example
 Creation Wizards page (in the New wizard).
 <br>&nbsp;
 <h3>
 Details</h3>
 The Readme Tool example declares one extension point and supplies a number
 of extensions.&nbsp; 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.&nbsp; 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&nbsp; 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>
	<!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 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 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>